New behaviour of GetMinPayoff and GetMaxPayoff to refer to plays of games (#655)

tturocy · rahulsavani · web-flow · commit 12f563d08918 · 2025-12-03T13:29:54.000Z
Previously, `GetMinPayoff` and `GetMaxPayoff` referred to the set of (non-null) outcomes in the game.  This is often not what you want when analysing a game:

* A terminal node with a null outcome is treated as a payoff of 0 and so should be taken into account;
* A contingency in the strategic game with a null outcome is treated as a payoff of 0 and so likewise;
* Outcomes at non-terminal nodes are supported; the "minimum" or "maximum" payoff in a game would be expected to be in reference to full plays of the game (cumulating payoffs).

This changes the behaviour of these functions to refer always to plays of the game, and adds new tests for {min,max}_payoff, {lp,lcp}_solve with EFGs w/ non-terminal/missing terminal outcomes.

---------

Co-authored-by: Rahul Savani &lt;rahul.savani@gmail.com&gt;
diff --git a/ChangeLog b/ChangeLog
@@ -7,6 +7,8 @@
   are always drawn and indicators are always drawn if an information set spans multiple levels.
 - In `pygambit`, indexing the children of a node by a string inteprets the string as an action label,
   not a label of a child node.  In addition, indexing by an action object is now supported. (#587)
+- In `pygambit`, `min_payoff` and `max_payoff` (for both games and players) now refers to payoffs in
+  any play of the game; previously this referred only to the set of outcomes. (#498)
 
 ### Added
 - Tests for EFG Nash solvers -- `enumpoly_solve`, `lp_solve`, `lcp_solve` -- in behavior stratgegies
diff --git a/src/games/game.h b/src/games/game.h
@@ -738,14 +738,14 @@ class GameRep : public std::enable_shared_from_this<GameRep> {
 
   /// Returns true if the game is constant-sum
   virtual bool IsConstSum() const = 0;
-  /// Returns the smallest payoff to any player in any outcome of the game
+  /// Returns the smallest payoff to any player in any play of the game
   virtual Rational GetMinPayoff() const = 0;
-  /// Returns the smallest payoff to the player in any outcome of the game
-  virtual Rational GetMinPayoff(const GamePlayer &p_player) const = 0;
-  /// Returns the largest payoff to any player in any outcome of the game
+  /// Returns the smallest payoff to the player in any play of the game
+  virtual Rational GetPlayerMinPayoff(const GamePlayer &p_player) const = 0;
+  /// Returns the largest payoff to any player in any play of the game
   virtual Rational GetMaxPayoff() const = 0;
-  /// Returns the largest payoff to the player in any outcome of the game
-  virtual Rational GetMaxPayoff(const GamePlayer &p_player) const = 0;
+  /// Returns the largest payoff to the player in any play of the game
+  virtual Rational GetPlayerMaxPayoff(const GamePlayer &p_player) const = 0;
 
   /// Returns the set of terminal nodes which are descendants of node
   virtual std::vector<GameNode> GetPlays(GameNode node) const { throw UndefinedException(); }
diff --git a/src/games/gameagg.h b/src/games/gameagg.h
@@ -89,11 +89,11 @@ class GameAGGRep : public GameRep {
   /// Returns the smallest payoff to any player in any outcome of the game
   Rational GetMinPayoff() const override { return Rational(aggPtr->getMinPayoff()); }
   /// Returns the smallest payoff to the player in any outcome of the game
-  Rational GetMinPayoff(const GamePlayer &) const override { throw UndefinedException(); }
+  Rational GetPlayerMinPayoff(const GamePlayer &) const override { throw UndefinedException(); }
   /// Returns the largest payoff to any player in any outcome of the game
   Rational GetMaxPayoff() const override { return Rational(aggPtr->getMaxPayoff()); }
   /// Returns the largest payoff to the player in any outcome of the game
-  Rational GetMaxPayoff(const GamePlayer &) const override { throw UndefinedException(); }
+  Rational GetPlayerMaxPayoff(const GamePlayer &) const override { throw UndefinedException(); }
   //@}
 
   /// @name Modification
diff --git a/src/games/gamebagg.h b/src/games/gamebagg.h
@@ -96,11 +96,11 @@ class GameBAGGRep : public GameRep {
   /// Returns the smallest payoff to any player in any outcome of the game
   Rational GetMinPayoff() const override { return Rational(baggPtr->getMinPayoff()); }
   /// Returns the smallest payoff to the player in any outcome of the game
-  Rational GetMinPayoff(const GamePlayer &) const override { throw UndefinedException(); }
+  Rational GetPlayerMinPayoff(const GamePlayer &) const override { throw UndefinedException(); }
   /// Returns the largest payoff to any player in any outcome of the game
   Rational GetMaxPayoff() const override { return Rational(baggPtr->getMaxPayoff()); }
   /// Returns the largest payoff to the player in any outcome of the game
-  Rational GetMaxPayoff(const GamePlayer &) const override { throw UndefinedException(); }
+  Rational GetPlayerMaxPayoff(const GamePlayer &) const override { throw UndefinedException(); }
   //@}
 
   /// @name Writing data files
diff --git a/src/games/gameexpl.cc b/src/games/gameexpl.cc
@@ -38,39 +38,19 @@ namespace Gambit {
 
 Rational GameExplicitRep::GetMinPayoff() const
 {
-  return std::accumulate(
-      std::next(m_players.begin()), m_players.end(), GetMinPayoff(m_players.front()),
-      [this](const Rational &r, const GamePlayer &p) { return std::min(r, GetMinPayoff(p)); });
-}
-
-Rational GameExplicitRep::GetMinPayoff(const GamePlayer &p_player) const
-{
-  if (m_outcomes.empty()) {
-    return Rational(0);
-  }
-  return std::accumulate(std::next(m_outcomes.begin()), m_outcomes.end(),
-                         m_outcomes.front()->GetPayoff<Rational>(p_player),
-                         [&p_player](const Rational &r, const std::shared_ptr<GameOutcomeRep> &c) {
-                           return std::min(r, c->GetPayoff<Rational>(p_player));
+  return std::accumulate(std::next(m_players.begin()), m_players.end(),
+                         GetPlayerMinPayoff(m_players.front()),
+                         [this](const Rational &r, const GamePlayer &p) {
+                           return std::min(r, GetPlayerMinPayoff(p));
                          });
 }
 
 Rational GameExplicitRep::GetMaxPayoff() const
 {
-  return std::accumulate(
-      std::next(m_players.begin()), m_players.end(), GetMaxPayoff(m_players.front()),
-      [this](const Rational &r, const GamePlayer &p) { return std::max(r, GetMaxPayoff(p)); });
-}
-
-Rational GameExplicitRep::GetMaxPayoff(const GamePlayer &p_player) const
-{
-  if (m_outcomes.empty()) {
-    return Rational(0);
-  }
-  return std::accumulate(std::next(m_outcomes.begin()), m_outcomes.end(),
-                         m_outcomes.front()->GetPayoff<Rational>(p_player),
-                         [&p_player](const Rational &r, const std::shared_ptr<GameOutcomeRep> &c) {
-                           return std::max(r, c->GetPayoff<Rational>(p_player));
+  return std::accumulate(std::next(m_players.begin()), m_players.end(),
+                         GetPlayerMaxPayoff(m_players.front()),
+                         [this](const Rational &r, const GamePlayer &p) {
+                           return std::max(r, GetPlayerMaxPayoff(p));
                          });
 }
 
diff --git a/src/games/gameexpl.h b/src/games/gameexpl.h
@@ -33,14 +33,10 @@ class GameExplicitRep : public GameRep {
 public:
   /// @name General data access
   //@{
-  /// Returns the smallest payoff to any player in any outcome of the game
+  /// Returns the smallest payoff to any player in any play of the game
   Rational GetMinPayoff() const override;
-  /// Returns the smallest payoff to the player in any outcome of the game
-  Rational GetMinPayoff(const GamePlayer &) const override;
-  /// Returns the largest payoff to any player in any outcome of the game
+  /// Returns the largest payoff to any player in any play of the game
   Rational GetMaxPayoff() const override;
-  /// Returns the largest payoff to the player in any outcome of the game
-  Rational GetMaxPayoff(const GamePlayer &) const override;
   //@}
 
   /// @name Dimensions of the game
diff --git a/src/games/gametable.cc b/src/games/gametable.cc
@@ -307,7 +307,8 @@ bool GameTableRep::IsConstSum() const
     sum += profile->GetPayoff(player);
   }
 
-  for (auto iter : StrategyContingencies(std::const_pointer_cast<GameRep>(shared_from_this()))) {
+  for (const auto iter :
+       StrategyContingencies(std::const_pointer_cast<GameRep>(shared_from_this()))) {
     Rational newsum(0);
     for (const auto &player : m_players) {
       newsum += iter->GetPayoff(player);
@@ -319,6 +320,26 @@ bool GameTableRep::IsConstSum() const
   return true;
 }
 
+Rational GameTableRep::GetPlayerMinPayoff(const GamePlayer &p_player) const
+{
+  Rational minpay = NewPureStrategyProfile()->GetPayoff(p_player);
+  for (const auto &profile :
+       StrategyContingencies(std::const_pointer_cast<GameRep>(shared_from_this()))) {
+    minpay = std::min(minpay, profile->GetPayoff(p_player));
+  }
+  return minpay;
+}
+
+Rational GameTableRep::GetPlayerMaxPayoff(const GamePlayer &p_player) const
+{
+  Rational maxpay = NewPureStrategyProfile()->GetPayoff(p_player);
+  for (const auto &profile :
+       StrategyContingencies(std::const_pointer_cast<GameRep>(shared_from_this()))) {
+    maxpay = std::max(maxpay, profile->GetPayoff(p_player));
+  }
+  return maxpay;
+}
+
 //------------------------------------------------------------------------
 //                   GameTableRep: Writing data files
 //------------------------------------------------------------------------
diff --git a/src/games/gametable.h b/src/games/gametable.h
@@ -57,6 +57,12 @@ class GameTableRep : public GameExplicitRep {
   //@{
   bool IsTree() const override { return false; }
   bool IsConstSum() const override;
+
+  /// Returns the smallest payoff to the player in any play of the game
+  Rational GetPlayerMinPayoff(const GamePlayer &) const override;
+  /// Returns the largest payoff to the player in any play of the game
+  Rational GetPlayerMaxPayoff(const GamePlayer &) const override;
+
   bool IsPerfectRecall() const override { return true; }
   //@}
 
diff --git a/src/games/gametree.cc b/src/games/gametree.cc
@@ -22,6 +22,7 @@
 
 #include <iostream>
 #include <algorithm>
+#include <functional>
 #include <numeric>
 #include <stack>
 #include <set>
@@ -719,10 +720,10 @@ Rational SubtreeSum(GameNode p_node)
   Rational sum(0);
 
   if (!p_node->IsTerminal()) {
-    auto children = p_node->GetChildren();
+    const auto children = p_node->GetChildren();
     sum = SubtreeSum(children.front());
     if (std::any_of(std::next(children.begin()), children.end(),
-                    [sum](GameNode n) { return SubtreeSum(n) != sum; })) {
+                    [sum](const GameNode &n) { return SubtreeSum(n) != sum; })) {
       throw NotZeroSumException();
     }
   }
@@ -735,6 +736,29 @@ Rational SubtreeSum(GameNode p_node)
   return sum;
 }
 
+Rational
+AggregateSubtreePayoff(const GamePlayer &p_player, const GameNode &p_node,
+                       std::function<Rational(const Rational &, const Rational &)> p_aggregator)
+{
+  if (p_node->IsTerminal()) {
+    if (p_node->GetOutcome()) {
+      return p_node->GetOutcome()->GetPayoff<Rational>(p_player);
+    }
+    return Rational(0);
+  }
+  const auto &children = p_node->GetChildren();
+  auto subtree =
+      std::accumulate(std::next(children.begin()), children.end(),
+                      AggregateSubtreePayoff(p_player, children.front(), p_aggregator),
+                      [&p_aggregator, &p_player](const Rational &r, const GameNode &c) {
+                        return p_aggregator(r, AggregateSubtreePayoff(p_player, c, p_aggregator));
+                      });
+  if (p_node->GetOutcome()) {
+    return subtree + p_node->GetOutcome()->GetPayoff<Rational>(p_player);
+  }
+  return subtree;
+}
+
 } // end anonymous namespace
 
 bool GameTreeRep::IsConstSum() const
@@ -748,6 +772,18 @@ bool GameTreeRep::IsConstSum() const
   }
 }
 
+Rational GameTreeRep::GetPlayerMinPayoff(const GamePlayer &p_player) const
+{
+  return AggregateSubtreePayoff(
+      p_player, m_root, [](const Rational &a, const Rational &b) { return std::min(a, b); });
+}
+
+Rational GameTreeRep::GetPlayerMaxPayoff(const GamePlayer &p_player) const
+{
+  return AggregateSubtreePayoff(
+      p_player, m_root, [](const Rational &a, const Rational &b) { return std::max(a, b); });
+}
+
 bool GameTreeRep::IsPerfectRecall() const
 {
   if (m_infosetParents.empty() && !m_root->IsTerminal()) {
diff --git a/src/games/gametree.h b/src/games/gametree.h
@@ -75,6 +75,11 @@ class GameTreeRep : public GameExplicitRep {
   bool IsTree() const override { return true; }
   bool IsConstSum() const override;
   bool IsPerfectRecall() const override;
+
+  /// Returns the smallest payoff to the player in any play of the game
+  Rational GetPlayerMinPayoff(const GamePlayer &) const override;
+  /// Returns the largest payoff to the player in any play of the game
+  Rational GetPlayerMaxPayoff(const GamePlayer &) const override;
   //@}
 
   /// @name Players
diff --git a/src/pygambit/gambit.pxd b/src/pygambit/gambit.pxd
@@ -290,9 +290,9 @@ cdef extern from "games/game.h":
 
         bool IsConstSum() except +
         c_Rational GetMinPayoff() except +
-        c_Rational GetMinPayoff(c_GamePlayer) except +
+        c_Rational GetPlayerMinPayoff(c_GamePlayer) except +
         c_Rational GetMaxPayoff() except +
-        c_Rational GetMaxPayoff(c_GamePlayer) except +
+        c_Rational GetPlayerMaxPayoff(c_GamePlayer) except +
         stdvector[c_GameNode] GetPlays(c_GameNode) except +
         stdvector[c_GameNode] GetPlays(c_GameInfoset) except +
         stdvector[c_GameNode] GetPlays(c_GameAction) except +
diff --git a/src/pygambit/game.pxi b/src/pygambit/game.pxi
@@ -790,12 +790,32 @@ class Game:
 
     @property
     def min_payoff(self) -> typing.Union[decimal.Decimal, Rational]:
-        """The minimum payoff in the game."""
+        """The minimum payoff to any player in any play of the game.
+
+        .. versionchanged:: 16.5.0
+           Changed from reporting minimum payoff in any (non-null) outcome to the minimum
+           payoff in any play of the game.
+
+        See also
+        --------
+        Game.max_payoff
+        Player.min_payoff
+        """
         return rat_to_py(self.game.deref().GetMinPayoff())
 
     @property
     def max_payoff(self) -> typing.Union[decimal.Decimal, Rational]:
-        """The maximum payoff in the game."""
+        """The maximum payoff to any player in any play of the game.
+
+        .. versionchanged:: 16.5.0
+           Changed from reporting maximum payoff in any (non-null) outcome to the maximum
+           payoff in any play of the game.
+
+        See also
+        --------
+        Game.min_payoff
+        Player.max_payoff
+        """
         return rat_to_py(self.game.deref().GetMaxPayoff())
 
     def set_chance_probs(self, infoset: typing.Union[Infoset, str], probs: typing.Sequence):
diff --git a/src/pygambit/player.pxi b/src/pygambit/player.pxi
@@ -241,10 +241,30 @@ class Player:
 
     @property
     def min_payoff(self) -> Rational:
-        """Returns the smallest payoff for the player in any outcome of the game."""
-        return rat_to_py(self.player.deref().GetGame().deref().GetMinPayoff(self.player))
+        """Returns the smallest payoff for the player in any play of the game.
+
+        .. versionchanged:: 16.5.0
+           Changed from reporting minimum payoff in any (non-null) outcome to the minimum
+           payoff in any play of the game.
+
+        See also
+        --------
+        Player.max_payoff
+        Game.min_payoff
+        """
+        return rat_to_py(self.player.deref().GetGame().deref().GetPlayerMinPayoff(self.player))
 
     @property
     def max_payoff(self) -> Rational:
-        """Returns the largest payoff for the player in any outcome of the game."""
-        return rat_to_py(self.player.deref().GetGame().deref().GetMaxPayoff(self.player))
+        """Returns the largest payoff for the player in any play of the game.
+
+        .. versionchanged:: 16.5.0
+           Changed from reporting maximum payoff in any (non-null) outcome to the maximum
+           payoff in any play of the game.
+
+        See also
+        --------
+        Player.min_payoff
+        Game.max_payoff
+        """
+        return rat_to_py(self.player.deref().GetGame().deref().GetPlayerMaxPayoff(self.player))
diff --git a/tests/games.py b/tests/games.py
diff --git a/tests/test_extensive.py b/tests/test_extensive.py
diff --git a/tests/test_games/payoff_game.nfg b/tests/test_games/payoff_game.nfg
diff --git a/tests/test_nash.py b/tests/test_nash.py
diff --git a/tests/test_players.py b/tests/test_players.py
diff --git a/tests/test_strategic.py b/tests/test_strategic.py
