From 983d75c41ccfe27a06dc14ffc9de03e4702d8e9f Mon Sep 17 00:00:00 2001 From: nataliemes Date: Thu, 15 Oct 2026 18:03:03 +0400 Subject: [PATCH 1/6] Update the front page --- doc/conf.py | 2 + doc/index.rst | 107 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 108 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 07a6759..c861e8c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -5,6 +5,8 @@ extensions = [ "sphinx.ext.autodoc", "sphinx.ext.autosummary", + "sphinx.ext.doctest", + "sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode", ] diff --git a/doc/index.rst b/doc/index.rst index 2832736..5473247 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,15 +3,120 @@ lemke **lemke** is a pure Python implementation of Lemke's algorithm for linear complementarity problems (LCPs), including its application to computing a -Nash equilibrium of a bimatrix game. +Nash equilibrium of a bimatrix game. It uses exact rational arithmetic +and is built for teaching and research, where you want to see each pivot. +It can be used as both a callable library and a CLI tool. + +lemke is part of the `Gambit project `_ for +computation in game theory, and it builds on the work of +`Bernhard von Stengel `_. + + +Features +-------- +- Lemke's algorithm for linear complementarity problems, + with a covering vector ``d``; +- Lexicographic minimum ratio test to handle degenerate problems; +- Arbitrary precision with integer pivoting; +- Lemke–Howson and the tracing procedure for bimatrix games; +- Verbose tableau output that shows every pivot; +- Command-line tools: ``lemke``, ``bimatrix`` and ``randomstart``. + + +Examples +-------- + +**1. Solving a 2×2 LCP in Python.** + +Find :math:`z \ge 0` with :math:`w = q + Mz \ge 0` and +:math:`z^\top w = 0`, where + +.. math:: + + M = \begin{pmatrix} 2 & 1 \\ 1 & 2 \end{pmatrix}, + \qquad + q = \begin{pmatrix} -1 \\ -1 \end{pmatrix}. + +.. doctest:: + + >>> from fractions import Fraction + >>> from lemke.lemke import lcp, runlemke + >>> m = [ + ... [Fraction(2), Fraction(1)], + ... [Fraction(1), Fraction(2)], + ... ] + >>> q = [Fraction(-1), Fraction(-1)] + >>> d = [Fraction(1), Fraction(1)] # covering vector + >>> problem = lcp(m, q, d) + >>> result = runlemke(lcp=problem) + >>> result.success + True + >>> result.z + (Fraction(1, 3), Fraction(1, 3)) + +The solution is exact: :math:`z = (1/3,\, 1/3)`, with :math:`w = 0`. + + +**2. Computing a Nash equilibrium from the command line.** + +Find Nash equilibria using the Lemke–Howson method for the bimatrix game +in ``examples/game``, where the payoff matrices are + +.. math:: + + A = \begin{pmatrix} 3 & 0 \\ 0 & 2 \end{pmatrix}, + \qquad + B = \begin{pmatrix} 2 & 0 \\ 0 & 7 \end{pmatrix}. + + +.. code-block:: console + + $ bimatrix lh examples/game + + +.. code-block:: text + + label 1 found eq (1,0),(1,0) + supports: [0][0] + label 2 found eq (0,1),(0,1) + supports: [1][1] + -------- equilibria found: -------- + (1,0),(1,0) + supports: [0][0] found by labels [1, 3] + (0,1),(0,1) + supports: [1][1] found by labels [2, 4] + +The algorithm runs for all labels by default and finds 2 equilibria. + Installation ------------ +lemke needs Python 3.10 or later. + +It is **not** yet available on PyPI, but can be installed directly from GitHub: + .. code-block:: console pip install git+https://github.com/gambitproject/lemke.git + +Citing lemke +------------ + +lemke is Free/Open Source software, released under the terms of +the GNU General Public Licence, version 3 (GPL-3.0). + +If you use lemke in a scientific publication, you can use the following citation: + + Von Stengel, B. (2026). *lemke: Lemke's algorithm for linear complementarity + problems and bimatrix games*. + https://github.com/gambitproject/lemke + + +API documentation +----------------- + .. toctree:: :maxdepth: 2 From 8b6205526907da627f8193de55736b041e126d0e Mon Sep 17 00:00:00 2001 From: nataliemes Date: Wed, 21 Oct 2026 01:03:14 +0400 Subject: [PATCH 2/6] Modify front page text --- doc/index.rst | 33 ++++++++++++++------------------- examples/lcp_2x2 | 5 +++++ 2 files changed, 19 insertions(+), 19 deletions(-) create mode 100644 examples/lcp_2x2 diff --git a/doc/index.rst b/doc/index.rst index 5473247..ce4db54 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -15,7 +15,7 @@ computation in game theory, and it builds on the work of Features -------- - Lemke's algorithm for linear complementarity problems, - with a covering vector ``d``; + with a covering vector :math:`d`; - Lexicographic minimum ratio test to handle degenerate problems; - Arbitrary precision with integer pivoting; - Lemke–Howson and the tracing procedure for bimatrix games; @@ -23,17 +23,18 @@ Features - Command-line tools: ``lemke``, ``bimatrix`` and ``randomstart``. -Examples --------- +Quick examples +-------------- -**1. Solving a 2×2 LCP in Python.** +Solve a 2×2 LCP in Python +~~~~~~~~~~~~~~~~~~~~~~~~~ -Find :math:`z \ge 0` with :math:`w = q + Mz \ge 0` and -:math:`z^\top w = 0`, where +Consider LCP given in ``examples/lcp_2x2``: find :math:`z \ge 0` +with :math:`w = q + Mz \ge 0` and :math:`z^\top w = 0`, where .. math:: - M = \begin{pmatrix} 2 & 1 \\ 1 & 2 \end{pmatrix}, + M = \begin{pmatrix} \frac{1}{2} & 1 \\ -1 & \frac{5}{2} \end{pmatrix}, \qquad q = \begin{pmatrix} -1 \\ -1 \end{pmatrix}. @@ -41,23 +42,18 @@ Find :math:`z \ge 0` with :math:`w = q + Mz \ge 0` and >>> from fractions import Fraction >>> from lemke.lemke import lcp, runlemke - >>> m = [ - ... [Fraction(2), Fraction(1)], - ... [Fraction(1), Fraction(2)], - ... ] - >>> q = [Fraction(-1), Fraction(-1)] - >>> d = [Fraction(1), Fraction(1)] # covering vector - >>> problem = lcp(m, q, d) + >>> problem = lcp.from_file("examples/lcp_2x2") >>> result = runlemke(lcp=problem) >>> result.success True >>> result.z - (Fraction(1, 3), Fraction(1, 3)) + (Fraction(2, 3), Fraction(2, 3)) -The solution is exact: :math:`z = (1/3,\, 1/3)`, with :math:`w = 0`. +The solution is exact: :math:`z = (\frac{2}{3}, \frac{2}{3})`, with :math:`w = 0`. -**2. Computing a Nash equilibrium from the command line.** +Find a Nash equilibrium from the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Find Nash equilibria using the Lemke–Howson method for the bimatrix game in ``examples/game``, where the payoff matrices are @@ -73,6 +69,7 @@ in ``examples/game``, where the payoff matrices are $ bimatrix lh examples/game +The algorithm runs for all labels by default and finds 2 equilibria: .. code-block:: text @@ -86,8 +83,6 @@ in ``examples/game``, where the payoff matrices are (0,1),(0,1) supports: [1][1] found by labels [2, 4] -The algorithm runs for all labels by default and finds 2 equilibria. - Installation ------------ diff --git a/examples/lcp_2x2 b/examples/lcp_2x2 new file mode 100644 index 0000000..a7c76a5 --- /dev/null +++ b/examples/lcp_2x2 @@ -0,0 +1,5 @@ +n= 2 +M= 1/2 1 + -1 2.5 +q= -1 -1 +d= 1 1 From 03fb64d6415d0d048e244c370d7591700e1381cb Mon Sep 17 00:00:00 2001 From: nataliemes Date: Wed, 21 Oct 2026 01:09:05 +0400 Subject: [PATCH 3/6] Fix shortened URL in the citation --- doc/conf.py | 1 + doc/index.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index c861e8c..4e0c586 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -32,4 +32,5 @@ "type": "fontawesome", } ], + "shorten_urls": False, } diff --git a/doc/index.rst b/doc/index.rst index ce4db54..4dcac84 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -106,7 +106,7 @@ If you use lemke in a scientific publication, you can use the following citation Von Stengel, B. (2026). *lemke: Lemke's algorithm for linear complementarity problems and bimatrix games*. - https://github.com/gambitproject/lemke + https://github.com/gambitproject/lemke. API documentation From bf9a1e77158fafe99bc1376e104c9b3e004f95a7 Mon Sep 17 00:00:00 2001 From: nataliemes Date: Wed, 21 Oct 2026 01:10:15 +0400 Subject: [PATCH 4/6] Update examples --- doc/index.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 4dcac84..3f6e0df 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -23,11 +23,14 @@ Features - Command-line tools: ``lemke``, ``bimatrix`` and ``randomstart``. -Quick examples +Usage examples -------------- -Solve a 2×2 LCP in Python -~~~~~~~~~~~~~~~~~~~~~~~~~ +Here are two quick examples of using lemke. +You can view more detailed explanations in the :doc:`tutorials`. + +1) Solve a 2×2 LCP in Python +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Consider LCP given in ``examples/lcp_2x2``: find :math:`z \ge 0` with :math:`w = q + Mz \ge 0` and :math:`z^\top w = 0`, where @@ -52,10 +55,10 @@ with :math:`w = q + Mz \ge 0` and :math:`z^\top w = 0`, where The solution is exact: :math:`z = (\frac{2}{3}, \frac{2}{3})`, with :math:`w = 0`. -Find a Nash equilibrium from the command line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +2) Find a Nash equilibrium from the CLI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Find Nash equilibria using the Lemke–Howson method for the bimatrix game +Find Nash equilibria with the Lemke–Howson method for the bimatrix game in ``examples/game``, where the payoff matrices are .. math:: From 1f01d36dac37f7db6a4be5e97427239cc2a36b55 Mon Sep 17 00:00:00 2001 From: nataliemes Date: Fri, 23 Oct 2026 19:20:16 +0400 Subject: [PATCH 5/6] Update examples --- doc/index.rst | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 3f6e0df..8064216 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -43,9 +43,16 @@ with :math:`w = q + Mz \ge 0` and :math:`z^\top w = 0`, where .. doctest:: - >>> from fractions import Fraction + >>> from fractions import Fraction as F >>> from lemke.lemke import lcp, runlemke - >>> problem = lcp.from_file("examples/lcp_2x2") + >>> problem = lcp( + ... M=[ + ... [F(1, 2), F(1)], + ... [F(-1), F(5, 2)], + ... ], + ... q=[F(-1), F(-1)], + ... d=[F(1), F(1)], + ... ) >>> result = runlemke(lcp=problem) >>> result.success True @@ -67,10 +74,24 @@ in ``examples/game``, where the payoff matrices are \qquad B = \begin{pmatrix} 2 & 0 \\ 0 & 7 \end{pmatrix}. +Save the following as ``game_file``:: + + # m,n= + 2 2 + + # A= + 3 0 + 0 2 + + # B= + 2 0 + 0 7 + +Then run: .. code-block:: console - $ bimatrix lh examples/game + $ bimatrix lh game_file The algorithm runs for all labels by default and finds 2 equilibria: From fd25f436e886943f8555daa1f8d771ea572ca1ec Mon Sep 17 00:00:00 2001 From: nataliemes Date: Fri, 23 Oct 2026 19:37:54 +0400 Subject: [PATCH 6/6] Fix tutorials link --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 8064216..04db35f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -27,7 +27,7 @@ Usage examples -------------- Here are two quick examples of using lemke. -You can view more detailed explanations in the :doc:`tutorials`. +You can view more detailed explanations in the :doc:`tutorials/index`. 1) Solve a 2×2 LCP in Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~