Add algorithms page

doc/algorithms.rst

@@ -0,0 +1,202 @@
+.. _algorithms:
+
+Nash equilibria algorithms
+==========================
+
+The table below summarizes the available PyGambit functions and corresponding Gambit CLI commandsto algorithms for computing Nash equilibria.
+Scroll down for detailed descriptions of each algorithm.
+
+================  ===========================================================================   ========================================  ==========================================
+Algorithm         Description                                                                   PyGambit function                         CLI command
+================  ===========================================================================   ========================================  ==========================================
+:ref:`enumpure`   Enumerate pure-strategy equilibria of a game                                  :py:func:`pygambit.nash.enumpure_solve`   :ref:`gambit-enumpure <gambit-enumpure>`
+:ref:`enummixed`  Enumerate equilibria in a two-player game                                     :py:func:`pygambit.nash.enummixed_solve`  :ref:`gambit-enummixed <gambit-enummixed>`
+:ref:`enumpoly`   Compute equilibria of a game using polynomial systems of equations            :py:func:`pygambit.nash.enumpoly_solve`   :ref:`gambit-enumpoly <gambit-enumpoly>`
+:ref:`lp`         Compute equilibria in a two-player constant-sum game via linear programming   :py:func:`pygambit.nash.lp_solve`         :ref:`gambit-lp <gambit-lp>`
+:ref:`lcp`        Compute equilibria in a two-player game via linear complementarity            :py:func:`pygambit.nash.lcp_solve`        :ref:`gambit-lcp <gambit-lcp>`
+:ref:`liap`       Compute Nash equilibria using function minimization                           :py:func:`pygambit.nash.liap_solve`       :ref:`gambit-liap <gambit-liap>`
+:ref:`logit`      Compute quantal response equilbria                                            :py:func:`pygambit.nash.logit_solve`      :ref:`gambit-logit <gambit-logit>`
+:ref:`simpdiv`    Compute equilibria via simplicial subdivision                                 :py:func:`pygambit.nash.simpdiv_solve`    :ref:`gambit-simpdiv <gambit-simpdiv>`
+:ref:`ipa`        Compute Nash equilibria using iterated polymatrix approximation               :py:func:`pygambit.nash.ipa_solve`        :ref:`gambit-ipa <gambit-ipa>`
+:ref:`gnm`        Compute Nash equilibria using a global Newton method                          :py:func:`pygambit.nash.gnm_solve`        :ref:`gambit-gnm <gambit-gnm>`
+================  ===========================================================================   ========================================  ==========================================
+
+.. _enumpure:
+
+enumpure
+--------
+
+Reads a game on standard input and searches for pure-strategy Nash equilibria.
+
+.. _enummixed:
+
+enummixed
+---------
+
+Reads a two-player game on standard input and computes Nash equilibria using extreme point enumeration.
+
+In a two-player strategic game, the set of Nash equilibria can be expressed as the union of convex sets.
+This program generates all the extreme points of those convex sets. (Mangasarian [Man64]_)
+This is a superset of the points generated by the path-following procedure of Lemke and Howson (see :ref:`lcp`).
+It was shown by Shapley [Sha74]_ that there are equilibria not accessible via the method in :ref:`lcp`, whereas the output of
+:program:`enummixed` is guaranteed to return all the extreme points.
+
+.. _enumpoly:
+
+enumpoly
+--------
+
+Reads a game on standard input and
+computes Nash equilibria by solving systems of polynomial equations
+and inequalities.
+
+This program searches for all Nash equilibria in a strategic game
+using a support enumeration approach. This approach computes all the
+supports which could, in principle, be the support of a Nash
+equilibrium.  For each candidate support, it attempts to compute
+totally mixed equilibria on that support by successively subdividing
+the space of mixed strategy profiles or mixed behavior profiles (as appropriate).
+By using the fact that the equilibrium conditions imply a collection
+of equations and inequalities which can be expressed as multilinear
+polynomials, the subdivision constructed is such that each cell
+contains either no equilibria or exactly one equilibrium.
+
+For strategic games, the program searches supports in the order proposed
+by Porter, Nudelman, and Shoham [PNS04]_.  For two-player games, this
+prioritises supports for which both players have the same number of
+strategies.  For games with three or more players, this prioritises
+supports which have the fewest strategies in total.  For many classes
+of games, this will tend to lower the average time until finding one equilibrium,
+as well as finding the second equilibrium (if one exists).
+
+.. _lp:
+
+lp
+---
+
+Reads a two-player constant-sum game on standard input
+and computes a Nash equilibrium by solving a linear program. The
+program uses the sequence form formulation of Koller, Megiddo, and von
+Stengel [KolMegSte94]_ for extensive games.
+
+While the set of equilibria in a two-player constant-sum strategic
+game is convex, this method will only identify one of the extreme
+points of that set.
+
+.. _lcp:
+
+lcp
+---
+
+Reads a two-player game on standard input and
+computes Nash equilibria by finding solutions to a linear
+complementarity problem. For extensive games, the program uses the
+sequence form representation of the extensive game, as defined by
+Koller, Megiddo, and von Stengel [KolMegSte94]_, and applies the
+algorithm developed by Lemke.
+
+For strategic games, the program uses the method of Lemke and Howson
+[LemHow64]_. In this case, the method will find all "accessible"
+equilibria, i.e., those that can be found as concatenations of Lemke-Howson
+paths that start at the artificial equilibrium.
+There exist strategic-form games for which some equilibria cannot be found
+by this method, i.e., some equilibria are inaccessible; see Shapley [Sha74]_.
+
+In a two-player strategic game, the set of Nash equilibria can be expressed
+as the union of convex sets. This program will find extreme points
+of those convex sets.  See :ref:`enummixed` for a method
+which is guaranteed to find all the extreme points for a strategic
+game.
+
+.. _liap:
+
+liap
+----
+
+Reads a game on standard input and computes
+approximate Nash equilibria using a function minimization approach.
+
+This procedure searches for equilibria by generating random starting
+points and using conjugate gradient descent to minimize the Lyapunov
+function of the game. This is a nonnegative function which is
+zero exactly at strategy profiles which are Nash equilibria.
+
+Note that this procedure is not globally convergent. That is, it is
+not guaranteed to find all, or even any, Nash equilibria.
+
+.. _logit:
+
+logit
+-----
+
+Reads a game on standard input and computes the
+principal branch of the (logit) quantal response correspondence.
+
+The method is based on the procedure described in Turocy [Tur05]_ for
+strategic games and Turocy [Tur10]_ for extensive games.
+It uses standard path-following methods (as
+described in Allgower and Georg's "Numerical Continuation Methods") to
+adaptively trace the principal branch of the correspondence
+efficiently and securely.
+
+The method used is a predictor-corrector method, which first generates
+a prediction using the differential equations describing the branch of
+the correspondence, followed by a corrector step which refines the
+prediction using Newton's method for finding a zero of a function. Two
+parameters control the operation of this tracing.
+
+In extensive games, logit quantal response equilibria are not well-defined
+if an information set is not reached due to being the successor of chance
+moves with zero probability.  In such games, the implementation treats
+the beliefs at such information sets as being uniform across all member nodes.
+
+.. _simpdiv:
+
+simpdiv
+--------
+
+Reads a game on standard input and computes
+approximations to Nash equilibria using a simplicial subdivision
+approach.
+
+This program implements the algorithm of van der Laan, Talman, and van
+Der Heyden [VTH87]_. The algorithm proceeds by constructing a triangulated grid
+over the space of mixed strategy profiles, and uses a path-following
+method to compute an approximate fixed point. This approximate fixed
+point can then be used as a starting point on a refinement of the
+grid. The program continues this process with finer and finer grids
+until locating a mixed strategy profile at which the maximum regret is
+small.
+
+.. _ipa:
+
+ipa
+---
+
+Reads a game on standard input and computes Nash
+equilibria using an iterated polymatrix approximation approach
+developed by Govindan and Wilson [GovWil04]_.
+This program is based on the
+`Gametracer 0.2 <http://dags.stanford.edu/Games/gametracer.html>`_
+implementation by Ben Blum and Christian Shelton.
+
+The algorithm takes as a parameter a mixed strategy profile.  This profile is
+interpreted as defining a ray in the space of games.  The profile must have
+the property that, for each player, the most frequently played strategy must
+be unique.
+
+.. _gnm:
+
+gnm
+---
+
+Reads a game on standard input and computes Nash
+equilibria using a global Newton method approach developed by Govindan
+and Wilson [GovWil03]_. This program is based on the
+`Gametracer 0.2 <http://dags.stanford.edu/Games/gametracer.html>`_
+implementation by Ben Blum and Christian Shelton.
+
+The algorithm takes as a parameter a mixed strategy profile.  This profile is
+interpreted as defining a ray in the space of games.  The profile must have
+the property that, for each player, the most frequently played strategy must
+be unique.

doc/index.rst

@@ -32,12 +32,12 @@ We recommended most new users install the PyGambit Python package and read the a
          :expand:
 
 
-   .. grid-item-card:: Command-line tools
+   .. grid-item-card:: Algorithms for computing Nash equilibria
       :columns: 6
 
-      Quickly compute equilibria with the Gambit command-line tools.
+      Read out documentation on the algorithms available in Gambit for computing Nash equilibria.
 
-      .. button-ref:: command-line
+      .. button-ref:: algorithms
          :ref-type: ref
          :click-parent:
          :color: secondary
@@ -61,6 +61,7 @@ We recommended most new users install the PyGambit Python package and read the a
    :maxdepth: 1
 
    install
+   algorithms
    pygambit
    tools
    gui

doc/pygambit.rst

@@ -55,26 +55,6 @@ These tutorials assume you have read the new user tutorials and are familiar wit
 
    tutorials/interoperability_tutorials/openspiel
 
-Algorithms for computing Nash equilibria
-----------------------------------------
-
-Interfaces to algorithms for computing Nash equilibria are provided in :py:mod:`pygambit.nash`.
-The table below summarizes the available PyGambit functions and the corresponding Gambit CLI commands.
-
-==========================================    ========================================
-CLI command                                   PyGambit function
-==========================================    ========================================
-:ref:`gambit-enumpure <gambit-enumpure>`      :py:func:`pygambit.nash.enumpure_solve`
-:ref:`gambit-enummixed <gambit-enummixed>`    :py:func:`pygambit.nash.enummixed_solve`
-:ref:`gambit-lp <gambit-lp>`                  :py:func:`pygambit.nash.lp_solve`
-:ref:`gambit-lcp <gambit-lcp>`                :py:func:`pygambit.nash.lcp_solve`
-:ref:`gambit-liap <gambit-liap>`              :py:func:`pygambit.nash.liap_solve`
-:ref:`gambit-logit <gambit-logit>`            :py:func:`pygambit.nash.logit_solve`
-:ref:`gambit-simpdiv <gambit-simpdiv>`        :py:func:`pygambit.nash.simpdiv_solve`
-:ref:`gambit-ipa <gambit-ipa>`                :py:func:`pygambit.nash.ipa_solve`
-:ref:`gambit-gnm <gambit-gnm>`                :py:func:`pygambit.nash.gnm_solve`
-==========================================    ========================================
-
 API documentation
 ----------------
 

doc/tools.enummixed.rst

@@ -3,18 +3,7 @@
 :program:`gambit-enummixed`: Enumerate equilibria in a two-player game
 ======================================================================
 
-:program:`gambit-enummixed` reads a two-player game on standard input and
-computes Nash equilibria using extreme point enumeration.
-
-In a two-player strategic game, the set of Nash equilibria can be expressed
-as the union of convex sets.  This program generates all the extreme
-points of those convex sets. (Mangasarian [Man64]_)
-This is a superset of the points generated by the path-following
-procedure of Lemke and Howson (see :ref:`gambit-lcp`).  It was
-shown by Shapley [Sha74]_ that there are equilibria not accessible via
-the method in :ref:`gambit-lcp`, whereas the output of
-:program:`gambit-enummixed` is guaranteed to return all the extreme
-points.
+:ref:`Algorithm description <enummixed>`
 
 .. program:: gambit-enummixed
 

doc/tools.enumpoly.rst

@@ -1,28 +1,9 @@
+.. _gambit-enumpoly:
+
 :program:`gambit-enumpoly`: Compute equilibria of a game using polynomial systems of equations
 ==============================================================================================
 
-:program:`gambit-enumpoly` reads a game on standard input and
-computes Nash equilibria by solving systems of polynomial equations
-and inequalities.
-
-This program searches for all Nash equilibria in a strategic game
-using a support enumeration approach. This approach computes all the
-supports which could, in principle, be the support of a Nash
-equilibrium.  For each candidate support, it attempts to compute
-totally mixed equilibria on that support by successively subdividing
-the space of mixed strategy profiles or mixed behavior profiles (as appropriate).
-By using the fact that the equilibrium conditions imply a collection
-of equations and inequalities which can be expressed as multilinear
-polynomials, the subdivision constructed is such that each cell
-contains either no equilibria or exactly one equilibrium.
-
-For strategic games, the program searches supports in the order proposed
-by Porter, Nudelman, and Shoham [PNS04]_.  For two-player games, this
-prioritises supports for which both players have the same number of
-strategies.  For games with three or more players, this prioritises
-supports which have the fewest strategies in total.  For many classes
-of games, this will tend to lower the average time until finding one equilibrium,
-as well as finding the second equilibrium (if one exists).
+:ref:`Algorithm description <enumpoly>`
 
 When the verbose switch `-v` is used, the program outputs each support
 as it is considered. The supports are presented as a comma-separated

doc/tools.enumpure.rst

@@ -3,8 +3,7 @@
 :program:`gambit-enumpure`: Enumerate pure-strategy equilibria of a game
 ========================================================================
 
-:program:`gambit-enumpure` reads a game on standard input and searches for
-pure-strategy Nash equilibria.
+:ref:`Algorithm description <enumpure>`
 
 .. versionchanged:: 14.0.2
    The effect of the `-S` switch is now purely cosmetic, determining

doc/tools.gnm.rst

@@ -3,16 +3,7 @@
 :program:`gambit-gnm`: Compute Nash equilibria in a strategic game using a global Newton method
 ===============================================================================================
 
-:program:`gambit-gnm` reads a game on standard input and computes Nash
-equilibria using a global Newton method approach developed by Govindan
-and Wilson [GovWil03]_. This program is based on the
-`Gametracer 0.2 <http://dags.stanford.edu/Games/gametracer.html>`_
-implementation by Ben Blum and Christian Shelton.
-
-The algorithm takes as a parameter a mixed strategy profile.  This profile is
-interpreted as defining a ray in the space of games.  The profile must have
-the property that, for each player, the most frequently played strategy must
-be unique.
+:ref:`Algorithm description <gnm>`
 
 The algorithm finds a subset of equilibria starting from any given profile.
 Multiple starting profiles may be generated via the `-n` option or specified

doc/tools.ipa.rst

@@ -3,17 +3,7 @@
 :program:`gambit-ipa`: Compute Nash equilibria in a strategic game using iterated polymatrix approximation
 ==========================================================================================================
 
-:program:`gambit-ipa` reads a game on standard input and computes Nash
-equilibria using an iterated polymatrix approximation approach
-developed by Govindan and Wilson [GovWil04]_.
-This program is based on the
-`Gametracer 0.2 <http://dags.stanford.edu/Games/gametracer.html>`_
-implementation by Ben Blum and Christian Shelton.
-
-The algorithm takes as a parameter a mixed strategy profile.  This profile is
-interpreted as defining a ray in the space of games.  The profile must have
-the property that, for each player, the most frequently played strategy must
-be unique.
+:ref:`Algorithm description <ipa>`
 
 The algorithm finds at most one equilibrium starting from any given profile.
 Multiple starting profiles may be generated via the `-n` option or specified

doc/tools.lcp.rst

@@ -4,28 +4,7 @@
 =========================================================================================
 
 
-:program:`gambit-lcp` reads a two-player game on standard input and
-computes Nash equilibria by finding solutions to a linear
-complementarity problem.
-
-For extensive games, the program uses the
-sequence form representation of the extensive game, as defined by
-Koller, Megiddo, and von Stengel [KolMegSte94]_, and applies the
-algorithm developed by Lemke. In that case, the method will find
-one Nash equilibrium.
-
-For strategic games, the program uses the method of Lemke and Howson
-[LemHow64]_. In this case, the method will find all "accessible"
-equilibria, i.e., those that can be found as concatenations of Lemke-Howson
-paths that start at the artificial equilibrium.
-There exist strategic-form games for which some equilibria cannot be found
-by this method, i.e., some equilibria are inaccessible; see Shapley [Sha74]_.
-
-In a two-player strategic game, the set of Nash equilibria can be expressed
-as the union of convex sets. This program will find extreme points
-of those convex sets.  See :ref:`gambit-enummixed` for a method
-which is guaranteed to find all the extreme points for a strategic
-game.
+:ref:`Algorithm description <lcp>`
 
 .. program:: gambit-lcp