Improve Nash algorithm selection and configuration in GUI

Makefile.am

@@ -411,6 +411,8 @@ gambit_SOURCES = \
 	src/gui/dlnashmon.cc \
 	src/gui/nashspec.cc \
 	src/gui/nashspec.h \
+	src/gui/nashvariants.cc \
+	src/gui/nashvariants.h \
 	src/gui/dlnewtable.cc \
 	src/gui/dlnewtable.h \
 	src/gui/dllogit.cc \

doc/gui.nash.rst

@@ -10,92 +10,246 @@ or click on the
 calculate icon on the toolbar.
 
 
-Selecting the method of computing equilibria
---------------------------------------------
-
-The process of computing Nash equilibria in extensive and strategic
-games is similar. This section focuses on the case of extensive games;
-the process for strategic games is analogous, except the extensive
-game-specific features, such as displaying the profiles on the game
-tree, are not applicable.
-
-Gambit provides guidance on the options for computing Nash equilibria
-in a dialog.
-The methods applicable to a particular game depend on three criteria:
-the number of equilibria to compute, whether the computation is to be
-done on the extensive or strategic games, and on details of the game,
-such as whether the game has two players or more, and whether the game
-is constant-sum.
-
-The first step in finding equilibria is to specify how many equilibria
-are to be found. Some algorithms for computing equilibria are adapted
-to finding a single equilibrium, while others attempt to compute the
-whole equilibrium set. The first drop-down in the dialog specifies how
-many equilibria to compute. In this drop-down there are options for
-:guilabel:`Compute one Nash equilibrium`, :guilabel:`Compute some Nash equilibria`,
-and, for two-player games, :guilabel:`Compute all Nash equilibria`.
-For some games, there exist algorithms which will
-compute many equilibria (relatively) efficiently, but are not
-guaranteed to find all equilibria.
-
-To simplify this process of choosing the method to compute equilibria,
-the second drop-down offers :guilabel:`Gambit's recommended method`.
-The recommendation is determined by the requested number of equilibria
-and the structure of the game as follows.
-
-=======================  =============================================  ==================
-Requested output         Game                                           Method
-=======================  =============================================  ==================
-One equilibrium          Two players and constant sum                   :ref:`lp`
-One equilibrium          Any other supported game                       :ref:`logit`
-Some equilibria          Two players                                    :ref:`lcp`
-Some equilibria          Three or more players                          :ref:`simpdiv`
-All equilibria           Two players                                    :ref:`enummixed`
-=======================  =============================================  ==================
-
-The :guilabel:`all equilibria` choice is therefore offered only for
-two-player games.  The recommendation selects an algorithm; it does not
-infer properties such as uniqueness.  In particular, "some" means that
-the selected method searches for multiple equilibria where possible, not
-that a particular number of distinct equilibria is guaranteed.
-
-For more control, the user can select one of the other methods shown in
-the second drop-down.  The list is filtered using the requested output
-category and the methods' applicability.  Methods which only operate on
-strategic games automatically select and lock the strategic
-representation.  Otherwise an extensive game may be solved using either
-its behavior representation or its reduced strategic representation.
-See :ref:`algorithms` for descriptions and limitations of the methods.
-
-The current dialog uses the following solver parameters.  They are
-recorded with each computation so that the interface can expose them for
-editing in a future revision.
+Choosing how to compute equilibria
+----------------------------------
+
+The :guilabel:`Compute equilibria` dialog helps you choose a method for
+computing Nash equilibria.  The choice is made in two steps: you state a
+**Goal**, and Gambit recommends a **variant** of one of its **methods**
+that suits the Goal and the game.  You can accept the recommendation or
+choose any other variant in the list.  The process is the same for
+extensive and strategic games.  For strategic games the variants that
+need a game tree are not listed, and the features specific to extensive
+games, such as displaying the profiles on the game tree, do not apply.
+
+The terms are used as follows.
+
+Goal
+   What you want from the computation, in terms of how many equilibria
+   are returned: :guilabel:`One equilibrium`, :guilabel:`Several
+   equilibria`, or :guilabel:`All equilibria`.  The Goal determines the
+   recommended variant and the default parameters.  It never removes
+   variants from the list.
+
+Method
+   An algorithm family, named as in :ref:`algorithms` (for example
+   ``lcp`` or ``simpdiv``).
+
+Variant
+   A method applied in a particular representation of the game.  Each
+   variant has its own coverage, reliability and solution concept.
+
+The Goal
+~~~~~~~~
+
+Some algorithms are adapted to finding a single equilibrium, while others
+attempt to compute the whole equilibrium set, and some compute many
+equilibria (relatively) efficiently without guaranteeing all of them.
+:guilabel:`All equilibria` is available only for games with two players,
+because Gambit has no method that guarantees all equilibria for games
+with more players; for such games the option is disabled, and a note
+beside it gives the reason.
+
+The variant list
+~~~~~~~~~~~~~~~~
+
+The list shows every variant that can be applied to the game's
+representations: variants that need a game tree are listed only for
+extensive games.  A variant that cannot be run on the game, for example
+because it is restricted to two-player games, is greyed out and cannot
+be selected; hovering over it shows the reason.  A variant that can be
+run but does not meet your Goal can still be selected, and the detail
+pane under the list then shows a warning saying what to expect.  A star
+marks the variant Gambit recommends for the current Goal.  The list can
+be sorted by clicking a column heading.  The columns are:
+
+:guilabel:`Method`
+   A description of the variant and the representation it works on.
+
+:guilabel:`Coverage`
+   Which equilibria the variant can be relied on to return.
+   :guilabel:`One` means a single equilibrium; :guilabel:`Some` means
+   possibly several equilibria, with no promise of finding all of them;
+   :guilabel:`All pure` means all equilibria in pure strategies, of
+   which there may be none; and :guilabel:`All` means every equilibrium.
+   :guilabel:`All` is claimed only where it is delivered in practice,
+   and only ``enummixed`` qualifies: it reports every extreme
+   equilibrium and describes each connected component of equilibria by
+   its extreme points.  Two methods that might be expected to qualify do
+   not:
+
+   * ``enumpoly`` can characterise all equilibria in theory, but it finds
+     isolated equilibria only.  It cannot represent a continuum of
+     equilibria on a support, and supports it cannot resolve are skipped.
+   * ``lcp`` finds only the equilibria reachable by the Lemke-Howson path
+     on the strategic form (the accessible equilibria), and returns just
+     one on the sequence form.
+
+:guilabel:`Reliability`
+   Whether the variant is guaranteed to return a result on a given game.
+   :guilabel:`Always` means it is.  :guilabel:`Usually` means it
+   converges in theory but may have problems with games that have some types
+   of degeneracy, which are common in practice.  :guilabel:`No guarantee`
+   means it is a local or heuristic search that is not known to converge
+   on every game.
+
+:guilabel:`Solves for`
+   The solution concept: :guilabel:`Nash`, or :guilabel:`Agent Nash`
+   (see :ref:`agent-nash-equilibria`).
+
+If the selected variant does not meet your Goal, a warning appears
+below the list.  A collapsible :guilabel:`Details` section shows the
+parameters the variant will run with.
+
+The recommendation
+~~~~~~~~~~~~~~~~~~
+
+The recommendation depends on the Goal and the structure of the game.
+It selects a method; it does not infer properties such as uniqueness.
+In particular, "several" means that the selected method searches for
+multiple equilibria where possible, not that a particular number of
+distinct equilibria is guaranteed.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 15 35
+
+   * - Goal
+     - Game
+     - Method
+     - Variant for an extensive game
+   * - One equilibrium
+     - Two players and constant sum
+     - :ref:`lp`
+     - Sequence form
+   * - One equilibrium
+     - Any other game
+     - :ref:`logit`
+     - Agent form
+   * - Several equilibria
+     - Two players
+     - :ref:`lcp`
+     - Strategic form (Lemke-Howson)
+   * - Several equilibria
+     - Three or more players
+     - :ref:`simpdiv`
+     - Strategic form
+   * - All equilibria
+     - Two players
+     - :ref:`enummixed`
+     - Strategic form
+
+The recommended variant is the one of the recommended method that is
+applicable to the game and meets the Goal, preferring the variant that
+works on the extensive game.  Hence for :guilabel:`Several equilibria`
+on a two-player extensive game the recommendation is Lemke-Howson on the
+strategic form, because the sequence-form variant of ``lcp`` returns
+only one equilibrium.  ``simpdiv`` is recommended over ``gnm`` for three
+or more players because it always returns a result, whereas ``gnm``
+may have problems with some types of degenerate games.  For strategic games every
+recommendation uses the strategic form.
+
+The dialog remembers your Goal and variant for each game while it is
+open: when you open the dialog again on the same game it starts with
+the choices you last made, provided that variant can still be run.  This
+memory is not saved with the game file.
+
+.. _method-variants:
+
+Why the representation is part of the choice
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An extensive game can be analysed directly, through its behavior
+strategies and sequence form, or through its reduced strategic form.  It
+is tempting to regard the choice of representation as a setting that can
+be applied to any method.  It is not: for many methods, applying the
+method to a different representation produces a different algorithm
+with different guarantees, so each combination is treated as a
+separate variant.  The differences are as follows.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Method
+     - What changes between representations
+   * - ``lp``
+     - The algorithms are theoretically equivalent, but the single
+       equilibrium returned can differ.
+   * - ``lcp``
+     - Theoretically different algorithms: Lemke on the sequence form
+       and Lemke-Howson on the strategic form.  The sequence-form
+       implementation returns one equilibrium; the strategic-form one
+       returns the accessible equilibria.
+   * - ``enumpoly``
+     - In theory the sequence form suffices.  In practice the sequence
+       form does not yet use dominance elimination, and the per-support
+       solvers mean some equilibria may be found in one representation
+       and not the other.
+   * - ``liap``, ``enumpure``
+     - Different solution concept: on the extensive game they compute
+       agent Nash equilibria, not Nash equilibria.
+   * - ``logit``
+     - Traces the agent quantal response equilibrium on the extensive
+       game, but its limit is a Nash equilibrium.
+
+For an extensive game, computation on the extensive representation is
+generally preferred when it is available, since it is often a
+significantly more compact representation of the strategic
+characteristics of the game than the reduced strategic game.  See
+:ref:`algorithms` for descriptions and limitations of the methods.
+
+.. _agent-nash-equilibria:
+
+Agent Nash equilibria
+~~~~~~~~~~~~~~~~~~~~~
+
+An *agent Nash equilibrium* is a behavior profile of an extensive game at
+which no agent can gain by deviating at its own information set alone.
+It is not necessarily a Nash equilibrium of the game: a profile may be
+stable against deviations at one information set at a time while a
+player could gain by changing play at several information sets
+together.
+
+The agent-form variants of ``enumpure`` and ``liap`` compute agent Nash
+equilibria, and their :guilabel:`Solves for` entry in the variant list
+reads :guilabel:`Agent Nash`.  The profiles they return are labelled as
+agent Nash equilibria in the description across the top of the profiles
+panel (for example, "One agent Nash equilibrium in pure strategies in
+extensive game"), so that they are not mistaken for Nash equilibria.  If
+Nash equilibria are what you need, use the strategic-form variants, or
+check the profiles returned.
+
+Parameters
+~~~~~~~~~~
+
+The :guilabel:`Details` section shows the parameters the selected variant will use.  They are shown for
+information and cannot be edited in the dialog.  They depend on the Goal
+only for ``enumpoly`` and ``simpdiv``.
 
 ================  ============================================================================
 Method            Parameters used by the graphical interface
 ================  ============================================================================
-``enumpure``      Enumerate all pure-strategy equilibria.
-``enummixed``     Enumerate all mixed-strategy extreme equilibria.
-``enumpoly``      Stop after the first equilibrium when "one" is requested; otherwise search all
-                  supports; maximum regret ``1e-4``.
+``enumpure``      No method-specific parameters.
+``enummixed``     No method-specific parameters.
+``enumpoly``      Stop after the first equilibrium when :guilabel:`One equilibrium` is the Goal;
+                  otherwise search all supports; maximum regret ``1e-4``.
 ``lp``            No method-specific parameters.
-``lcp``           Search all accessible equilibria; unlimited recursion depth.
-``liap``          10 random starting points; 1,000 iterations per point; maximum regret ``1e-4``.
+``lcp``           All accessible equilibria; unlimited recursion depth.
+``liap``          10 random starting points; at most 1,000 iterations per point; maximum
+                  regret ``1e-4``.
 ``logit``         Maximum regret ``1e-8``; initial step ``0.03``; maximum acceleration ``1.1``.
-``simpdiv``       One random starting point when "one" is requested, otherwise 20; denominator
-                  100; grid resize factor 2; maximum regret ``1/10000000``.
+``simpdiv``       One random starting point when :guilabel:`One equilibrium` is the Goal,
+                  otherwise 20; denominator 100; grid resize factor 2; maximum regret
+                  ``1/10000000``.
 ``ipa``           One random perturbation.
 ``gnm``           One random perturbation; ending lambda ``-10``; 100 steps per support cell;
                   local Newton refinement every 3 steps, with at most 10 iterations.
-``hp``            No method-specific parameters.
+``hp``            10 random priors; maximum regret ``1e-8``.
 ================  ============================================================================
 
-For extensive games, there is an option of whether to use the
-extensive or strategic game for computation when the selected method
-supports both. In general, computation
-using the extensive game is preferred, since it is often a
-significantly more compact representation of the strategic
-characteristics of the game than the reduced strategic game is.
+Running the computation
+~~~~~~~~~~~~~~~~~~~~~~~
 
 For even moderate sized games, computation of equilibrium can be a
 time-intensive process. Gambit runs all computations in the