Terminology for agent versus "standard" values in extensive games (#642)

This clarifies and standardises terminology for "standard Nash" versus "(multi)agent Nash".

* What was previously being called `liap_value` and `*_regret` in mixed behaviour profiles is actually the *agent* versions of these concepts.  The functions have been renamed accordingly (prefixed by `agent_`).
* New versions of `liap_value` and `*_regret` are now provided, which compute the standard values of these concepts (currently, by passing to the corresponding mixed strategy profile).
* Two methods, `enumpure` and `liap`, were actually computing agent profiles.  These have been changed to have versions with `agent` in the name.  Other methods on the extensive form do actually compute Nash equilibria, and so they are not changed.

Closes #617

* For mixed behaviors renamed `liap_value` -> `agent_liap_value` and `max_regret` -> `agent_max_regret` in Python

* Rename agent functions in MixedBehaviorProfile

* Separated out `enumpure_agent_solve` function for clarity.

* Add `liap_agent_solve` and remove that functionality from `liap_solve` for expositional clarity.

* Change interface of `gambit-liap` to be more similar to `gambit-enumpure`

* Change GUI behavior to use only strategic for enumpure and liap

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

* fixed typo: self.__max_regret -> self._max_regret

* tests for max_regret/infoset regret on mixed behavior profiles

* added tests/test_games/myerson_fig_4_2.efg

* Added comprehensive tests for GameStructureChangedError (#700)

* agent_{liap_value,max_regret} added to tests for GameStructureChangedError

* Fix incorrect function called in MixedBehaviorProfile.liap_value

* remove xfail from test for Myerson fig 4.2 agent versus non-agent liap value

* title and comment in tests/test_games/myerson_fig_4_2.efg

* notebook showing agent versus non-agent notions

* missing file

* using liap_solve and enummixed_solv in 04_agent_versus_non_agent_regret.ipynb

* improve 04_agent_versus_non_agent_regret.ipynb

* move to advanced_tutorials/agent_versus_non_agent_regret.ipynb

* fix relative import

* agent -> non-agent max_regret/liap_solve in 03_stripped_down_poker.ipynb

* removed use_strategic from call to logit_solve in 03_stripped_down_poker.ipynb

* Updated ChangeLog.

* fixing up enumpoly tests

* problem cases shown in tests

* test_regrets_tmp

* clearer example of (one) problem

* test demonstrating issue is to do with infoset order

* test demonstrating issue is to do with infoset order

* Previous test failures were due to not calling `.sort_infosets()` prior to analysis.

We are going to remove `.sort_infosets()` separately; for the moment this adjusts the tests to add an explicit call to clear the errors for clarity.

* Tidy up tests now that information set sorting is obsolete.

---------

Co-authored-by: Rahul Savani <rahul.savani@gmail.com>

Author: tturocy

ChangeLog

@@ -7,6 +7,10 @@
   to detect if an information is absent-minded.
 
 ### Changed
+- Terminology for agent-form calculations on extensive games has been clarified.  Mixed behavior profiles
+  distinguish "agent" regret and liap values from their strategy-based analogs.  Methods which compute
+  using the agent-form - specifically `enumpure_solve` and `liap_solve`, now clarify this by being named
+  differently in `pygambit`. (#617)
 - In the graphical interface, removed option to configure information set link drawing; information sets
   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,

contrib/games/myerson_fig_4_2.efg

@@ -0,0 +1,15 @@
+EFG 2 R "Myerson (1991) Fig 4.2" { "Player 1" "Player 2" }
+"An example from Myerson (1991) Fig 4.2 which has an agent Nash equilibrium that is
+not a Nash equilibrium"
+
+p "" 1 1 "" { "A1" "B1" } 0
+p "" 2 1 "" { "W2" "X2" } 0
+p "" 1 2 "" { "Y1" "Z1" } 0
+t "" 1 "" { 3, 0 }
+t "" 2 "" { 0, 0 }
+p "" 1 2 "" { "Y1" "Z1" } 0
+t "" 3 "" { 2, 3 }
+t "" 4 "" { 4, 1 }
+p "" 2 1 "" { "W2" "X2" } 0
+t "" 5 "" { 2, 3 }
+t "" 6 "" { 3, 2 }

doc/pygambit.api.rst

@@ -258,6 +258,8 @@ Probability distributions over behavior
    MixedBehaviorProfile.infoset_prob
    MixedBehaviorProfile.belief
    MixedBehaviorProfile.is_defined_at
+   MixedBehaviorProfile.agent_max_regret
+   MixedBehaviorProfile.agent_liap_value
    MixedBehaviorProfile.max_regret
    MixedBehaviorProfile.liap_value
    MixedBehaviorProfile.as_strategy
@@ -297,11 +299,13 @@ Computation of Nash equilibria
 
    NashComputationResult
    enumpure_solve
+   enumpure_agent_solve
    enummixed_solve
    enumpoly_solve
    lp_solve
    lcp_solve
    liap_solve
+   liap_agent_solve
    logit_solve
    simpdiv_solve
    ipa_solve

doc/tools.enumpure.rst

@@ -38,10 +38,10 @@ pure-strategy Nash equilibria.
 
    .. versionadded:: 14.0.2
 
-   Report agent form equilibria, that is, equilibria which consider
-   only deviations at one information set.  Only has an effect for
-   extensive games, as strategic games have only one information set
-   per player.
+   Report agent Nash equilibria, that is, equilibria which consider
+   only deviations at a single information set at a time.  Only has
+   an effect for extensive games, as strategic games have only
+   one information set per player.
 
 .. cmdoption:: -h
 

doc/tools.liap.rst

@@ -26,8 +26,24 @@ not guaranteed to find all, or even any, Nash equilibria.
    in terms of the maximum regret.  This regret is interpreted as a fraction
    of the difference between the maximum and minimum payoffs in the game.
 
+.. versionchanged:: 16.5.0
+
+   The `-A` switch has been introduced to be explicit in choosing to compute
+   agent Nash equilibria.  The default is now to compute using the strategic
+   form even for extensive games.
+
+
 .. program:: gambit-liap
 
+.. cmdoption:: -A
+
+   .. versionadded:: 16.5.0
+
+   Report agent Nash equilibria, that is, equilibria which consider
+   only deviations at a single information set at a time.  Only has
+   an effect for extensive games, as strategic games have only
+   one information set per player.
+
 .. cmdoption:: -d
 
    Express all output using decimal representations with the