Implement new (correct) max_regret and liap_value on mixed behaviour profiles

Author: tturocy

doc/pygambit.api.rst

@@ -259,6 +259,8 @@ Probability distributions over behavior
    MixedBehaviorProfile.is_defined_at
    MixedBehaviorProfile.agent_max_regret
    MixedBehaviorProfile.agent_liap_value
+   MixedBehaviorProfile.max_regret
+   MixedBehaviorProfile.liap_value
    MixedBehaviorProfile.as_strategy
    MixedBehaviorProfile.normalize
    MixedBehaviorProfile.copy

src/games/behavmixed.cc

@@ -261,6 +261,11 @@ template <class T> MixedBehaviorProfile<T> MixedBehaviorProfile<T>::ToFullSuppor
 //              MixedBehaviorProfile<T>: Interesting quantities
 //========================================================================
 
+template <class T> T MixedBehaviorProfile<T>::GetLiapValue() const
+{
+  return MixedStrategyProfile<T>(*this).GetLiapValue();
+}
+
 template <class T> T MixedBehaviorProfile<T>::GetAgentLiapValue() const
 {
   CheckVersion();
@@ -364,6 +369,11 @@ template <class T> T MixedBehaviorProfile<T>::GetRegret(const GameInfoset &p_inf
   return br_payoff - map_infosetValues[p_infoset];
 }
 
+template <class T> T MixedBehaviorProfile<T>::GetMaxRegret() const
+{
+  return MixedStrategyProfile<T>(*this).GetMaxRegret();
+}
+
 template <class T> T MixedBehaviorProfile<T>::GetAgentMaxRegret() const
 {
   return maximize_function(m_support.GetGame()->GetInfosets(),

src/games/behavmixed.h

@@ -174,6 +174,7 @@ template <class T> class MixedBehaviorProfile {
   //@{
   T GetPayoff(int p_player) const;
   T GetPayoff(const GamePlayer &p_player) const { return GetPayoff(p_player->GetNumber()); }
+  T GetLiapValue() const;
   T GetAgentLiapValue() const;
 
   const T &GetRealizProb(const GameNode &node) const;
@@ -191,7 +192,7 @@ template <class T> class MixedBehaviorProfile {
   ///          between the best-response payoff and the payoff to playing
   ///          \p p_action.
   /// @param[in] p_action  The action to compute the regret for.
-  /// @sa GetRegret(const GameInfoset &) const;
+  /// @sa GetRegret(const GameInfoset &) const
   ///     GetAgentMaxRegret() const
   const T &GetRegret(const GameAction &p_action) const;
 
@@ -201,16 +202,22 @@ template <class T> class MixedBehaviorProfile {
   ///          as the difference between the payoff of the best response action and
   ///          the payoff to playing their specified mixed action.
   /// @param[in] p_infoset  The information set to compute the regret at.
-  /// @sa GetRegret(const GameAction &) const;
+  /// @sa GetRegret(const GameAction &) const
   ///     GetAgentMaxRegret() const
   T GetRegret(const GameInfoset &p_infoset) const;
 
   /// @brief Computes the maximum regret at any information set in the profile
   /// @details Computes the maximum of the regrets of the information sets in the profile.
-  /// @sa GetRegret(const GameInfoset &) const;
+  /// @sa GetRegret(const GameInfoset &) const
   ///     GetRegret(const GameAction &) const
+  ///     GetMaxRegret() const
   T GetAgentMaxRegret() const;
 
+  /// @brief Computes the maximum regret for any player in the profile
+  /// @sa GetAgentMaxRegret() const
+  ///
+  T GetMaxRegret() const;
+
   T DiffActionValue(const GameAction &action, const GameAction &oppAction) const;
   T DiffRealizProb(const GameNode &node, const GameAction &oppAction) const;
   T DiffNodeValue(const GameNode &node, const GamePlayer &player,

src/pygambit/behavmixed.pxi

@@ -819,7 +819,7 @@ class MixedBehaviorProfile:
     def agent_max_regret(self) -> ProfileDType:
         """Returns the maximum regret at any information set.
 
-        A profile is an agent Nash equilibrium if and only if `max_regret()` is 0.
+        A profile is an agent Nash equilibrium if and only if `agent_max_regret()` is 0.
 
         .. versionchanged:: 16.5.0
 
@@ -830,6 +830,7 @@ class MixedBehaviorProfile:
         --------
         action_regret
         infoset_regret
+        max_regret
         agent_liap_value
         """
         self._check_validity()
@@ -838,7 +839,7 @@ class MixedBehaviorProfile:
     def agent_liap_value(self) -> ProfileDType:
         """Returns the Lyapunov value (see [McK91]_) of the strategy profile.
 
-        The Lyapunov value is a non-negative number which is zero exactly at
+        The agent Lyapunov value is a non-negative number which is zero exactly at
         agent Nash equilibria.
 
         .. versionchanged:: 16.5.0
@@ -849,6 +850,44 @@ class MixedBehaviorProfile:
         See Also
         --------
         agent_max_regret
+        liap_value
+        """
+        self._check_validity()
+        return self._agent_liap_value()
+
+    def max_regret(self) -> ProfileDType:
+        """Returns the maximum regret at any information set.
+
+        A profile is a Nash equilibrium if and only if `max_regret()` is 0.
+
+        .. versionchanged:: 16.5.0
+
+           New implementation of `max_regret` to clarify the distinction between
+           per-player and per-agent concepts.
+
+        See Also
+        --------
+        liap_value
+        agent_max_regret
+        """
+        self._check_validity()
+        return self.__max_regret()
+
+    def liap_value(self) -> ProfileDType:
+        """Returns the Lyapunov value (see [McK91]_) of the strategy profile.
+
+        The Lyapunov value is a non-negative number which is zero exactly at
+        Nash equilibria.
+
+        .. versionchanged:: 16.5.0
+
+           New implementation of `liap_value` to clarify the distinction between
+           per-player and per-agent concepts.
+
+        See Also
+        --------
+        max_regret
+        agent_liap_value
         """
         self._check_validity()
         return self._agent_liap_value()
@@ -932,6 +971,9 @@ class MixedBehaviorProfileDouble(MixedBehaviorProfile):
     def _agent_max_regret(self) -> float:
         return deref(self.profile).GetAgentMaxRegret()
 
+    def _max_regret(self) -> float:
+        return deref(self.profile).GetMaxRegret()
+
     def __eq__(self, other: typing.Any) -> bool:
         return (
             isinstance(other, MixedBehaviorProfileDouble) and
@@ -951,6 +993,9 @@ class MixedBehaviorProfileDouble(MixedBehaviorProfile):
     def _agent_liap_value(self) -> float:
         return deref(self.profile).GetAgentLiapValue()
 
+    def _liap_value(self) -> float:
+        return deref(self.profile).GetLiapValue()
+
     def _normalize(self) -> MixedBehaviorProfileDouble:
         return MixedBehaviorProfileDouble.wrap(
             make_shared[c_MixedBehaviorProfile[double]](deref(self.profile).Normalize())
@@ -1028,6 +1073,9 @@ class MixedBehaviorProfileRational(MixedBehaviorProfile):
     def _agent_max_regret(self) -> Rational:
         return rat_to_py(deref(self.profile).GetAgentMaxRegret())
 
+    def _max_regret(self) -> Rational:
+        return rat_to_py(deref(self.profile).GetMaxRegret())
+
     def __eq__(self, other: typing.Any) -> bool:
         return (
             isinstance(other, MixedBehaviorProfileRational) and
@@ -1047,6 +1095,9 @@ class MixedBehaviorProfileRational(MixedBehaviorProfile):
     def _agent_liap_value(self) -> Rational:
         return rat_to_py(deref(self.profile).GetAgentLiapValue())
 
+    def _liap_value(self) -> Rational:
+        return rat_to_py(deref(self.profile).GetLiapValue())
+
     def _normalize(self) -> MixedBehaviorProfileRational:
         return MixedBehaviorProfileRational.wrap(
             make_shared[c_MixedBehaviorProfile[c_Rational]](deref(self.profile).Normalize())

src/pygambit/gambit.pxd

@@ -378,6 +378,8 @@ cdef extern from "games/behavmixed.h" namespace "Gambit":
         T GetRegret(c_GameInfoset) except +
         T GetAgentMaxRegret() except +
         T GetAgentLiapValue() except +
+        T GetMaxRegret() except +
+        T GetLiapValue() except +
         c_MixedStrategyProfile[T] ToMixedProfile()  # except + doesn't compile
         c_MixedBehaviorProfile(c_MixedStrategyProfile[T]) except +NotImplementedError
         c_MixedBehaviorProfile(c_Game) except +