From c08f59c0933d2e6d488e4d3b4f9bfb94aa1687d7 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 15:13:24 +0000 Subject: [PATCH 01/15] Add new algorithms documentation page --- doc/algorithms.rst | 21 +++++++++++++++++++++ doc/index.rst | 7 ++++--- doc/pygambit.rst | 20 -------------------- 3 files changed, 25 insertions(+), 23 deletions(-) create mode 100644 doc/algorithms.rst diff --git a/doc/algorithms.rst b/doc/algorithms.rst new file mode 100644 index 000000000..8f3ec51d3 --- /dev/null +++ b/doc/algorithms.rst @@ -0,0 +1,21 @@ +.. _algorithms: + +Nash equilibria algorithms +========================== + +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 ` :py:func:`pygambit.nash.enumpure_solve` +:ref:`gambit-enummixed ` :py:func:`pygambit.nash.enummixed_solve` +:ref:`gambit-lp ` :py:func:`pygambit.nash.lp_solve` +:ref:`gambit-lcp ` :py:func:`pygambit.nash.lcp_solve` +:ref:`gambit-liap ` :py:func:`pygambit.nash.liap_solve` +:ref:`gambit-logit ` :py:func:`pygambit.nash.logit_solve` +:ref:`gambit-simpdiv ` :py:func:`pygambit.nash.simpdiv_solve` +:ref:`gambit-ipa ` :py:func:`pygambit.nash.ipa_solve` +:ref:`gambit-gnm ` :py:func:`pygambit.nash.gnm_solve` +========================================== ======================================== diff --git a/doc/index.rst b/doc/index.rst index 22560eca3..c497d0a3d 100644 --- a/doc/index.rst +++ b/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 @@ -62,6 +62,7 @@ We recommended most new users install the PyGambit Python package and read the a intro install + algorithms pygambit tools gui diff --git a/doc/pygambit.rst b/doc/pygambit.rst index cf4302efa..8d8f624fb 100644 --- a/doc/pygambit.rst +++ b/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 ` :py:func:`pygambit.nash.enumpure_solve` -:ref:`gambit-enummixed ` :py:func:`pygambit.nash.enummixed_solve` -:ref:`gambit-lp ` :py:func:`pygambit.nash.lp_solve` -:ref:`gambit-lcp ` :py:func:`pygambit.nash.lcp_solve` -:ref:`gambit-liap ` :py:func:`pygambit.nash.liap_solve` -:ref:`gambit-logit ` :py:func:`pygambit.nash.logit_solve` -:ref:`gambit-simpdiv ` :py:func:`pygambit.nash.simpdiv_solve` -:ref:`gambit-ipa ` :py:func:`pygambit.nash.ipa_solve` -:ref:`gambit-gnm ` :py:func:`pygambit.nash.gnm_solve` -========================================== ======================================== - API documentation ---------------- From 6503a627073fdbd319e06e9f9054c30045fb79ab Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 15:45:42 +0000 Subject: [PATCH 02/15] refactor table --- doc/algorithms.rst | 81 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 68 insertions(+), 13 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 8f3ec51d3..3bf1f9dbd 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -6,16 +6,71 @@ Nash equilibria algorithms 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 ` :py:func:`pygambit.nash.enumpure_solve` -:ref:`gambit-enummixed ` :py:func:`pygambit.nash.enummixed_solve` -:ref:`gambit-lp ` :py:func:`pygambit.nash.lp_solve` -:ref:`gambit-lcp ` :py:func:`pygambit.nash.lcp_solve` -:ref:`gambit-liap ` :py:func:`pygambit.nash.liap_solve` -:ref:`gambit-logit ` :py:func:`pygambit.nash.logit_solve` -:ref:`gambit-simpdiv ` :py:func:`pygambit.nash.simpdiv_solve` -:ref:`gambit-ipa ` :py:func:`pygambit.nash.ipa_solve` -:ref:`gambit-gnm ` :py:func:`pygambit.nash.gnm_solve` -========================================== ======================================== +================ =========================================================================== ======================================== ========================================== +Algorithm Description PyGambit function CLI command +================ =========================================================================== ======================================== ========================================== +:ref:`enumpure` Enumerate pure-strategy equilibria of a game :py:func:`pygambit.nash.enumpure_solve` :ref:`gambit-enumpure ` +:ref:`enummixed` Enumerate equilibria in a two-player game :py:func:`pygambit.nash.enummixed_solve` :ref:`gambit-enummixed ` +:ref:`lp` Compute equilibria in a two-player constant-sum game via linear programming :py:func:`pygambit.nash.lp_solve` :ref:`gambit-lp ` +:ref:`lcp` Compute equilibria in a two-player game via linear complementarity :py:func:`pygambit.nash.lcp_solve` :ref:`gambit-lcp ` +:ref:`liap` Compute Nash equilibria using function minimization :py:func:`pygambit.nash.liap_solve` :ref:`gambit-liap ` +:ref:`logit` Compute quantal response equilbria :py:func:`pygambit.nash.logit_solve` :ref:`gambit-logit ` +:ref:`simpdiv` Compute equilibria via simplicial subdivision :py:func:`pygambit.nash.simpdiv_solve` :ref:`gambit-simpdiv ` +:ref:`ipa` Compute Nash equilibria using iterated polymatrix approximation :py:func:`pygambit.nash.ipa_solve` :ref:`gambit-ipa ` +:ref:`gnm` Compute Nash equilibria using a global Newton method :py:func:`pygambit.nash.gnm_solve` :ref:`gambit-gnm ` +================ =========================================================================== ======================================== ========================================== + +.. _enumpure: + +enumpure +-------- + +.. _enummixed: + +enummixed +--------- + +.. _enumpoly: + +enumpoly +-------- + +.. _lcp: + +lcp +--- + +.. _lp: + +lp +--- + +.. _liap: + +liap +---- + +.. _simpdiv: + +simpdiv +-------- + +.. _logit: + +logit +----- + +.. _gnm: + +gnm +--- + +.. _ipa: + +ipa +--- + +.. _convert: + +convert +------- From c7b80d47b2b40ff2a179c269cf1bc8bb4b8af647 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:07:10 +0000 Subject: [PATCH 03/15] enumpure desc --- doc/algorithms.rst | 2 ++ doc/tools.enumpure.rst | 3 +-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 3bf1f9dbd..91ddce619 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -25,6 +25,8 @@ Algorithm Description enumpure -------- +Reads a game on standard input and searches for pure-strategy Nash equilibria. + .. _enummixed: enummixed diff --git a/doc/tools.enumpure.rst b/doc/tools.enumpure.rst index f9dfafc9e..9eccbce8c 100644 --- a/doc/tools.enumpure.rst +++ b/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 ` .. versionchanged:: 14.0.2 The effect of the `-S` switch is now purely cosmetic, determining From 6ab416feef17150a531cd4e0fa6875024cb01455 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:10:44 +0000 Subject: [PATCH 04/15] move enummixed description to algorithms.rst --- doc/algorithms.rst | 8 ++++++++ doc/tools.enummixed.rst | 13 +------------ 2 files changed, 9 insertions(+), 12 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 91ddce619..de9e5ee8a 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -32,6 +32,14 @@ Reads a game on standard input and searches for pure-strategy Nash equilibria. 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 diff --git a/doc/tools.enummixed.rst b/doc/tools.enummixed.rst index 8a2432672..933b50360 100644 --- a/doc/tools.enummixed.rst +++ b/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 ` .. program:: gambit-enummixed From c11974ec939484e3f4a1d10c5cbbf512e46ea190 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:15:37 +0000 Subject: [PATCH 05/15] Add enumpoly algorithm --- doc/algorithms.rst | 24 ++++++++++++++++++++++++ doc/tools.enumpoly.rst | 23 +---------------------- 2 files changed, 25 insertions(+), 22 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index de9e5ee8a..86112b671 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -11,6 +11,7 @@ Algorithm Description ================ =========================================================================== ======================================== ========================================== :ref:`enumpure` Enumerate pure-strategy equilibria of a game :py:func:`pygambit.nash.enumpure_solve` :ref:`gambit-enumpure ` :ref:`enummixed` Enumerate equilibria in a two-player game :py:func:`pygambit.nash.enummixed_solve` :ref:`gambit-enummixed ` +:ref:`enumpoly` Compute equilibria of a game using polynomial systems of equations :py:func:`pygambit.nash.enumpoly_solve` :ref:`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 ` :ref:`lcp` Compute equilibria in a two-player game via linear complementarity :py:func:`pygambit.nash.lcp_solve` :ref:`gambit-lcp ` :ref:`liap` Compute Nash equilibria using function minimization :py:func:`pygambit.nash.liap_solve` :ref:`gambit-liap ` @@ -45,6 +46,29 @@ It was shown by Shapley [Sha74]_ that there are equilibria not accessible via th 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). + .. _lcp: lcp diff --git a/doc/tools.enumpoly.rst b/doc/tools.enumpoly.rst index f3c46bd9a..91aaa257c 100644 --- a/doc/tools.enumpoly.rst +++ b/doc/tools.enumpoly.rst @@ -1,28 +1,7 @@ :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 ` When the verbose switch `-v` is used, the program outputs each support as it is considered. The supports are presented as a comma-separated From eb9313bc4673d850b32dac31457d758b5b2b909d Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:17:12 +0000 Subject: [PATCH 06/15] Add lp --- doc/algorithms.rst | 17 +++++++++++++---- doc/tools.lp.rst | 10 +--------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 86112b671..f8b0d7ac0 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -69,14 +69,23 @@ 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). -.. _lcp: +.. _lp: -lcp +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. -lp +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 --- .. _liap: diff --git a/doc/tools.lp.rst b/doc/tools.lp.rst index efa47563d..f4d6a4d31 100644 --- a/doc/tools.lp.rst +++ b/doc/tools.lp.rst @@ -3,15 +3,7 @@ :program:`gambit-lp`: Compute equilibria in a two-player constant-sum game via linear programming ================================================================================================= -:program:`gambit-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. - +:ref:`Algorithm description ` .. program:: gambit-lp From e529e6ba212e9cb7b31e21fbc609afa46c5230cc Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:18:15 +0000 Subject: [PATCH 07/15] add lcp --- doc/algorithms.rst | 16 ++++++++++++++++ doc/tools.lcp.rst | 16 +--------------- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index f8b0d7ac0..0f6ffc9ad 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -88,6 +88,22 @@ points of that set. 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 using +the method of Lemke and Howson [LemHow64]_. There exist strategic +games for which some equilibria cannot be located by this method; 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 diff --git a/doc/tools.lcp.rst b/doc/tools.lcp.rst index 62eb424f5..f23a78ae0 100644 --- a/doc/tools.lcp.rst +++ b/doc/tools.lcp.rst @@ -4,21 +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. For strategic games, the program using -the method of Lemke and Howson [LemHow64]_. There exist strategic -games for which some equilibria cannot be located by this method; 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 ` .. program:: gambit-lcp From f9d97e4176289c04f5d99fd16f3f87381adb7200 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:19:08 +0000 Subject: [PATCH 08/15] add liap --- doc/algorithms.rst | 11 +++++++++++ doc/tools.liap.rst | 11 +---------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 0f6ffc9ad..012041f77 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -109,6 +109,17 @@ game. 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. + .. _simpdiv: simpdiv diff --git a/doc/tools.liap.rst b/doc/tools.liap.rst index 561059d45..b1284423b 100644 --- a/doc/tools.liap.rst +++ b/doc/tools.liap.rst @@ -3,16 +3,7 @@ :program:`gambit-liap`: Compute Nash equilibria using function minimization =========================================================================== -:program:`gambit-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. +:ref:`Algorithm description ` .. versionchanged:: 16.2.0 From 22c76d24f5c9e4856e8dcb09eeab3f00d9c4f33f Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:21:09 +0000 Subject: [PATCH 09/15] add logit --- doc/algorithms.rst | 31 ++++++++++++++++++++++++++----- doc/tools.logit.rst | 23 +++-------------------- 2 files changed, 29 insertions(+), 25 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 012041f77..8502fe605 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -120,16 +120,37 @@ 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. -.. _simpdiv: - -simpdiv --------- - .. _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 +-------- + .. _gnm: gnm diff --git a/doc/tools.logit.rst b/doc/tools.logit.rst index 59eaf7e52..27d9cbbef 100644 --- a/doc/tools.logit.rst +++ b/doc/tools.logit.rst @@ -3,21 +3,9 @@ :program:`gambit-logit`: Compute quantal response equilbria =========================================================== -:program:`gambit-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. The option `-s` sets +:ref:`Algorithm description ` + +The option `-s` sets the initial step size for the predictor phase of the tracing. This step size is then dynamically adjusted based on the rate of convergence of Newton's method in the corrector step. If the @@ -28,11 +16,6 @@ Turocy [Tur05]_, this acceleration helps to efficiently trace the correspondence when it reaches its asymptotic phase for large values of the precision parameter lambda. -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. - .. versionchanged:: 16.2.0 The criterion for accepting whether a point is sufficiently close to a From 619744408af7a332c09866735a443ff60584348c Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:22:15 +0000 Subject: [PATCH 10/15] add simpdiv --- doc/algorithms.rst | 13 +++++++++++++ doc/tools.simpdiv.rst | 13 +------------ 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 8502fe605..08485590f 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -151,6 +151,19 @@ the beliefs at such information sets as being uniform across all member nodes. 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. + .. _gnm: gnm diff --git a/doc/tools.simpdiv.rst b/doc/tools.simpdiv.rst index 324025dd6..6c5856df0 100644 --- a/doc/tools.simpdiv.rst +++ b/doc/tools.simpdiv.rst @@ -3,18 +3,7 @@ :program:`gambit-simpdiv`: Compute equilibria via simplicial subdivision ======================================================================== -:program:`gambit-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. +:ref:`Algorithm description ` The algorithm begins with any mixed strategy profile consisting of rational numbers as probabilities. Without any options, the algorithm From 2e85159bc9de514e7e180019ff551d7d4f159517 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:24:04 +0000 Subject: [PATCH 11/15] add ipa --- doc/algorithms.rst | 23 +++++++++++++++-------- doc/tools.ipa.rst | 12 +----------- 2 files changed, 16 insertions(+), 19 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 08485590f..6fe77140d 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -164,17 +164,24 @@ grid. The program continues this process with finer and finer grids until locating a mixed strategy profile at which the maximum regret is small. -.. _gnm: - -gnm ---- - .. _ipa: ipa --- -.. _convert: +: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 `_ +implementation by Ben Blum and Christian Shelton. -convert -------- +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 +--- diff --git a/doc/tools.ipa.rst b/doc/tools.ipa.rst index 219faa95b..f8c762da5 100644 --- a/doc/tools.ipa.rst +++ b/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 `_ -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 ` The algorithm finds at most one equilibrium starting from any given profile. Multiple starting profiles may be generated via the `-n` option or specified From 1ed1abfef5e05882831570b2360e42387aaf759e Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:25:08 +0000 Subject: [PATCH 12/15] add gnm --- doc/algorithms.rst | 13 ++++++++++++- doc/tools.gnm.rst | 11 +---------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index 6fe77140d..fbdb85afe 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -169,7 +169,7 @@ small. ipa --- -:program:`gambit-ipa` reads a game on standard input and computes Nash +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 @@ -185,3 +185,14 @@ be unique. 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 `_ +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. diff --git a/doc/tools.gnm.rst b/doc/tools.gnm.rst index 88ca23eb4..70f069993 100644 --- a/doc/tools.gnm.rst +++ b/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 `_ -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 ` The algorithm finds a subset of equilibria starting from any given profile. Multiple starting profiles may be generated via the `-n` option or specified From f8945c90ea23807f384dbd07ac59d67e5aed4f69 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:35:59 +0000 Subject: [PATCH 13/15] update links in nash.py --- src/pygambit/nash.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/pygambit/nash.py b/src/pygambit/nash.py index 6579d11db..9e937c7ac 100644 --- a/src/pygambit/nash.py +++ b/src/pygambit/nash.py @@ -66,7 +66,7 @@ class NashComputationResult: def enumpure_solve(game: libgbt.Game, use_strategic: bool = True) -> NashComputationResult: - """Compute all :ref:`pure-strategy Nash equilibria ` of game. + """Compute all :ref:`pure-strategy Nash equilibria ` of game. Parameters ---------- @@ -105,7 +105,7 @@ def enummixed_solve( rational: bool = True, lrsnash_path: pathlib.Path | str | None = None, ) -> NashComputationResult: - """Compute all :ref:`mixed-strategy Nash equilibria ` + """Compute all :ref:`mixed-strategy Nash equilibria ` of a two-player game using the strategic representation. Parameters @@ -168,7 +168,7 @@ def lcp_solve( max_depth: int | None = None ) -> NashComputationResult: """Compute Nash equilibria of a two-player game using :ref:`linear - complementarity programming `. + complementarity programming `. Parameters ---------- @@ -234,7 +234,7 @@ def lp_solve( use_strategic: bool = False ) -> NashComputationResult: """Compute Nash equilibria of a two-player constant-sum game using :ref:`linear - programming `. + programming `. Parameters ---------- @@ -283,7 +283,7 @@ def liap_solve( maxiter: int = 1000 ) -> NashComputationResult: """Compute approximate Nash equilibria of a game using - :ref:`Lyapunov function minimization `. + :ref:`Lyapunov function minimization `. .. versionchanged:: 16.2.0 @@ -345,7 +345,7 @@ def simpdiv_solve( leash: int | None = None ) -> NashComputationResult: """Compute Nash equilibria of a game using :ref:`simplicial - subdivision `. + subdivision `. .. versionchanged:: 16.2.0 @@ -404,7 +404,7 @@ def ipa_solve( perturbation: libgbt.Game | libgbt.MixedStrategyProfileDouble, ) -> NashComputationResult: """Compute Nash equilibria of a game using :ref:`iterated polymatrix - approximation `. + approximation `. Parameters ---------- @@ -460,7 +460,7 @@ def gnm_solve( local_newton_maxits: int = 10, ) -> NashComputationResult: """Compute Nash equilibria of a game using :ref:`a global Newton - method `. + method `. Parameters ---------- @@ -585,9 +585,9 @@ def enumpoly_solve( maxregret: float = 1.0e-4, phcpack_path: pathlib.Path | str | None = None ) -> NashComputationResult: - """Compute Nash equilibria by enumerating all support profiles of strategies - or actions, and for each support finding all totally-mixed equilibria of - the game over that support. + """:ref:`Compute Nash equilibria by enumerating all support profiles + of strategies or actions, and for each support finding all totally-mixed equilibria of + the game over that support.` Parameters ---------- @@ -671,7 +671,7 @@ def logit_solve( max_accel: float = 1.1, ) -> NashComputationResult: """Compute Nash equilibria of a game using :ref:`the logit quantal response - equilibrium correspondence `. + equilibrium correspondence `. Returns an approximation to the limiting point on the principal branch of the correspondence for the game. From 223baebc444177e96811e66bbe2ae3be9d04d9b7 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Mon, 8 Dec 2025 16:49:26 +0000 Subject: [PATCH 14/15] update high level page description --- doc/algorithms.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/algorithms.rst b/doc/algorithms.rst index fbdb85afe..b85e351a9 100644 --- a/doc/algorithms.rst +++ b/doc/algorithms.rst @@ -3,8 +3,8 @@ Nash equilibria algorithms ========================== -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. +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 From 6ba68078f28b855d50f268ea397be64f917d9295 Mon Sep 17 00:00:00 2001 From: Ted Turocy Date: Thu, 11 Dec 2025 10:00:00 +0000 Subject: [PATCH 15/15] Add xref anchor for enumpoly tool --- doc/tools.enumpoly.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/tools.enumpoly.rst b/doc/tools.enumpoly.rst index 91aaa257c..6bf9a43ba 100644 --- a/doc/tools.enumpoly.rst +++ b/doc/tools.enumpoly.rst @@ -1,3 +1,5 @@ +.. _gambit-enumpoly: + :program:`gambit-enumpoly`: Compute equilibria of a game using polynomial systems of equations ==============================================================================================