diff --git a/doc/algorithms.rst b/doc/algorithms.rst new file mode 100644 index 000000000..e954cbd37 --- /dev/null +++ b/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 ` +: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 ` +: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 +-------- + +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 `_ +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 `_ +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/index.rst b/doc/index.rst index 79076153a..733fadd36 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 @@ -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 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 ---------------- diff --git a/doc/tools.enummixed.rst b/doc/tools.enummixed.rst index c3ad6df12..bda408129 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 diff --git a/doc/tools.enumpoly.rst b/doc/tools.enumpoly.rst index a04362e98..1379fe0b0 100644 --- a/doc/tools.enumpoly.rst +++ b/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 ` When the verbose switch `-v` is used, the program outputs each support as it is considered. The supports are presented as a comma-separated diff --git a/doc/tools.enumpure.rst b/doc/tools.enumpure.rst index c653bc7bd..055ccfaba 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 diff --git a/doc/tools.gnm.rst b/doc/tools.gnm.rst index 7bd63c3cc..90fffe833 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 diff --git a/doc/tools.ipa.rst b/doc/tools.ipa.rst index adac09b2f..88a0a101d 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 diff --git a/doc/tools.lcp.rst b/doc/tools.lcp.rst index 19b62d812..8a747eeda 100644 --- a/doc/tools.lcp.rst +++ b/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 ` .. program:: gambit-lcp diff --git a/doc/tools.liap.rst b/doc/tools.liap.rst index fdac11f51..974961da5 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 diff --git a/doc/tools.logit.rst b/doc/tools.logit.rst index 908cb201c..fb3f50242 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 diff --git a/doc/tools.lp.rst b/doc/tools.lp.rst index f09e97663..b91e0f83d 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 diff --git a/doc/tools.simpdiv.rst b/doc/tools.simpdiv.rst index ccebe633c..6956e4606 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 diff --git a/src/pygambit/nash.py b/src/pygambit/nash.py index 8a39c038b..e771a9e4b 100644 --- a/src/pygambit/nash.py +++ b/src/pygambit/nash.py @@ -66,7 +66,7 @@ class NashComputationResult: def enumpure_solve(game: libgbt.Game) -> NashComputationResult: - """Compute all :ref:`pure-strategy Nash equilibria ` of game. + """Compute all :ref:`pure-strategy Nash equilibria ` of game. .. versionchanged:: 16.5.0 @@ -131,7 +131,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 @@ -194,7 +194,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 ---------- @@ -269,7 +269,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 ---------- @@ -318,7 +318,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 @@ -423,7 +423,7 @@ def simpdiv_solve( leash: int | None = None ) -> NashComputationResult: """Compute Nash equilibria of a game using :ref:`simplicial - subdivision `. + subdivision `. .. versionchanged:: 16.2.0 @@ -482,7 +482,7 @@ def ipa_solve( perturbation: libgbt.Game | libgbt.MixedStrategyProfileDouble, ) -> NashComputationResult: """Compute Nash equilibria of a game using :ref:`iterated polymatrix - approximation `. + approximation `. Parameters ---------- @@ -538,7 +538,7 @@ def gnm_solve( local_newton_maxits: int = 10, ) -> NashComputationResult: """Compute Nash equilibria of a game using :ref:`a global Newton - method `. + method `. Parameters ---------- @@ -663,9 +663,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 ---------- @@ -749,7 +749,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.