jlgametheory 0.1.0__tar.gz

jlgametheory-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, QuantEcon
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

jlgametheory-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: jlgametheory
+Version: 0.1.0
+Summary: Python interface to GameTheory.jl
+Author: QuantEcon
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: quantecon>=0.8
+Requires-Dist: juliacall>=0.9.20
+Requires-Dist: sphinx>=8.0 ; extra == "docs"
+Requires-Dist: sphinx-copybutton ; extra == "docs"
+Requires-Dist: pytest>=7 ; extra == "test"
+Requires-Dist: pytest-cov>=4 ; extra == "test"
+Project-URL: Homepage, https://github.com/QuantEcon/jlgametheory
+Project-URL: Repository, https://github.com/QuantEcon/jlgametheory
+Provides-Extra: docs
+Provides-Extra: test
+
+# jlgametheory
+
+[![Build Status](https://github.com/QuantEcon/jlgametheory/actions/workflows/ci.yml/badge.svg)](https://github.com/QuantEcon/jlgametheory/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/QuantEcon/jlgametheory/badge.svg)](https://coveralls.io/github/QuantEcon/jlgametheory)
+[![Documentation (latest)](https://img.shields.io/badge/docs-latest-blue.svg)](https://quantecon.github.io/jlgametheory/latest/)
+
+Python interface to GameTheory.jl
+
+`jlgametheory` is a Python package that allows passing
+a `NormalFormGame` instance from
+[`QuantEcon.py`](https://github.com/QuantEcon/QuantEcon.py) to
+[`GameTheory.jl`](https://github.com/QuantEcon/GameTheory.jl) functions
+via [`JuliaCall`](https://github.com/JuliaPy/PythonCall.jl).
+
+## Implemented functions
+
+* [`lrsnash`](https://quantecon.github.io/jlgametheory/latest/_autosummary/jlgametheory.lrsnash.html):
+  Compute in exact arithmetic all extreme mixed-action Nash equilibria of a 2-player normal form game with integer payoffs.
+* [`hc_solve`](https://quantecon.github.io/jlgametheory/latest/_autosummary/jlgametheory.hc_solve.html):
+  Compute all isolated mixed-action Nash equilibria of an N-player normal form game.
+
+## Example usage
+
+```python
+import quantecon.game_theory as gt
+import jlgametheory as jgt
+```
+
+### lrsnash
+
+`lrsnash` calls the Nash equilibrium computation routine in [lrslib](http://cgm.cs.mcgill.ca/~avis/C/lrs.html)
+(through its Julia wrapper [LRSLib.jl](https://github.com/JuliaPolyhedra/LRSLib.jl)):
+
+```python
+bimatrix = [[(3, 3), (3, 2)],
+            [(2, 2), (5, 6)],
+            [(0, 3), (6, 1)]]
+g = gt.NormalFormGame(bimatrix)
+jgt.lrsnash(g)
+```
+
+```
+[(array([Fraction(4, 5), Fraction(1, 5), Fraction(0, 1)], dtype=object),
+  array([Fraction(2, 3), Fraction(1, 3)], dtype=object)),
+ (array([Fraction(0, 1), Fraction(1, 3), Fraction(2, 3)], dtype=object),
+  array([Fraction(1, 3), Fraction(2, 3)], dtype=object)),
+ (array([Fraction(1, 1), Fraction(0, 1), Fraction(0, 1)], dtype=object),
+  array([Fraction(1, 1), Fraction(0, 1)], dtype=object))]
+```
+
+### hc_solve
+
+`hc_solve` computes all isolated Nash equilibria of an N-player game by using
+[HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl):
+
+```python
+g = gt.NormalFormGame((2, 2, 2))
+g[0, 0, 0] = 9, 8, 12
+g[1, 1, 0] = 9, 8, 2
+g[0, 1, 1] = 3, 4, 6
+g[1, 0, 1] = 3, 4, 4
+jgt.hc_solve(g)
+```
+
+```
+[(array([0., 1.]), array([0., 1.]), array([1., 0.])),
+ (array([0.5, 0.5]), array([0.5, 0.5]), array([1.000e+00, 2.351e-38])),
+ (array([1., 0.]), array([0., 1.]), array([-1.881e-37,  1.000e+00])),
+ (array([0.25, 0.75]), array([0.5, 0.5]), array([0.333, 0.667])),
+ (array([0.25, 0.75]), array([1.000e+00, 1.345e-43]), array([0.25, 0.75])),
+ (array([0., 1.]), array([0.333, 0.667]), array([0.333, 0.667])),
+ (array([1., 0.]), array([ 1.00e+00, -5.74e-42]), array([1., 0.])),
+ (array([0., 1.]), array([1., 0.]), array([2.374e-66, 1.000e+00])),
+ (array([0.5, 0.5]), array([0.333, 0.667]), array([0.25, 0.75]))]
+```
+
+## Tutorials
+
+* [Tools for Game Theory in QuantEcon.py](https://nbviewer.jupyter.org/github/QuantEcon/game-theory-notebooks/blob/main/game_theory_py.ipynb)
+* [Tools for Game Theory in GameTheory.jl](https://nbviewer.jupyter.org/github/QuantEcon/game-theory-notebooks/blob/main/game_theory_jl.ipynb)
+

jlgametheory-0.1.0/README.md

@@ -0,0 +1,80 @@
+# jlgametheory
+
+[![Build Status](https://github.com/QuantEcon/jlgametheory/actions/workflows/ci.yml/badge.svg)](https://github.com/QuantEcon/jlgametheory/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/QuantEcon/jlgametheory/badge.svg)](https://coveralls.io/github/QuantEcon/jlgametheory)
+[![Documentation (latest)](https://img.shields.io/badge/docs-latest-blue.svg)](https://quantecon.github.io/jlgametheory/latest/)
+
+Python interface to GameTheory.jl
+
+`jlgametheory` is a Python package that allows passing
+a `NormalFormGame` instance from
+[`QuantEcon.py`](https://github.com/QuantEcon/QuantEcon.py) to
+[`GameTheory.jl`](https://github.com/QuantEcon/GameTheory.jl) functions
+via [`JuliaCall`](https://github.com/JuliaPy/PythonCall.jl).
+
+## Implemented functions
+
+* [`lrsnash`](https://quantecon.github.io/jlgametheory/latest/_autosummary/jlgametheory.lrsnash.html):
+  Compute in exact arithmetic all extreme mixed-action Nash equilibria of a 2-player normal form game with integer payoffs.
+* [`hc_solve`](https://quantecon.github.io/jlgametheory/latest/_autosummary/jlgametheory.hc_solve.html):
+  Compute all isolated mixed-action Nash equilibria of an N-player normal form game.
+
+## Example usage
+
+```python
+import quantecon.game_theory as gt
+import jlgametheory as jgt
+```
+
+### lrsnash
+
+`lrsnash` calls the Nash equilibrium computation routine in [lrslib](http://cgm.cs.mcgill.ca/~avis/C/lrs.html)
+(through its Julia wrapper [LRSLib.jl](https://github.com/JuliaPolyhedra/LRSLib.jl)):
+
+```python
+bimatrix = [[(3, 3), (3, 2)],
+            [(2, 2), (5, 6)],
+            [(0, 3), (6, 1)]]
+g = gt.NormalFormGame(bimatrix)
+jgt.lrsnash(g)
+```
+
+```
+[(array([Fraction(4, 5), Fraction(1, 5), Fraction(0, 1)], dtype=object),
+  array([Fraction(2, 3), Fraction(1, 3)], dtype=object)),
+ (array([Fraction(0, 1), Fraction(1, 3), Fraction(2, 3)], dtype=object),
+  array([Fraction(1, 3), Fraction(2, 3)], dtype=object)),
+ (array([Fraction(1, 1), Fraction(0, 1), Fraction(0, 1)], dtype=object),
+  array([Fraction(1, 1), Fraction(0, 1)], dtype=object))]
+```
+
+### hc_solve
+
+`hc_solve` computes all isolated Nash equilibria of an N-player game by using
+[HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl):
+
+```python
+g = gt.NormalFormGame((2, 2, 2))
+g[0, 0, 0] = 9, 8, 12
+g[1, 1, 0] = 9, 8, 2
+g[0, 1, 1] = 3, 4, 6
+g[1, 0, 1] = 3, 4, 4
+jgt.hc_solve(g)
+```
+
+```
+[(array([0., 1.]), array([0., 1.]), array([1., 0.])),
+ (array([0.5, 0.5]), array([0.5, 0.5]), array([1.000e+00, 2.351e-38])),
+ (array([1., 0.]), array([0., 1.]), array([-1.881e-37,  1.000e+00])),
+ (array([0.25, 0.75]), array([0.5, 0.5]), array([0.333, 0.667])),
+ (array([0.25, 0.75]), array([1.000e+00, 1.345e-43]), array([0.25, 0.75])),
+ (array([0., 1.]), array([0.333, 0.667]), array([0.333, 0.667])),
+ (array([1., 0.]), array([ 1.00e+00, -5.74e-42]), array([1., 0.])),
+ (array([0., 1.]), array([1., 0.]), array([2.374e-66, 1.000e+00])),
+ (array([0.5, 0.5]), array([0.333, 0.667]), array([0.25, 0.75]))]
+```
+
+## Tutorials
+
+* [Tools for Game Theory in QuantEcon.py](https://nbviewer.jupyter.org/github/QuantEcon/game-theory-notebooks/blob/main/game_theory_py.ipynb)
+* [Tools for Game Theory in GameTheory.jl](https://nbviewer.jupyter.org/github/QuantEcon/game-theory-notebooks/blob/main/game_theory_jl.ipynb)

jlgametheory-0.1.0/jlgametheory/__init__.py

@@ -0,0 +1,22 @@
+"""
+jlgametheory: Python interface to GameTheory.jl
+
+"""
+from juliacall import Main as jl
+from importlib.metadata import PackageNotFoundError, version as _version
+
+jl.seval("using GameTheory")
+GameTheory = jl.GameTheory
+
+from .jlgametheory import (
+    lrsnash, hc_solve
+)
+
+try:
+    __version__ = _version("jlgametheory")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0+unknown"
+
+__all__ = [
+    "lrsnash", "hc_solve"
+]

jlgametheory-0.1.0/jlgametheory/jlgametheory.py

@@ -0,0 +1,163 @@
+import numpy as np
+from . import GameTheory
+
+
+def to_jl_nfg(g):
+    g_jl = GameTheory.NormalFormGame(
+        *(GameTheory.Player(player.payoff_array) for player in g.players)
+    )
+    return g_jl
+
+
+def _to_py_ne(NE_jl):
+    return tuple(x.to_numpy() for x in NE_jl)
+
+
+def _to_py_nes(NEs_jl):
+    return [_to_py_ne(NE) for NE in NEs_jl]
+
+
+def lrsnash(g):
+    """
+    Compute in exact arithmetic all extreme mixed-action Nash equilibria
+    of a 2-player normal form game with integer payoffs. This function
+    calls the Nash equilibrium computation routine in `lrslib` (through
+    its Julia wrapper `LRSLib.jl`) which is based on the "lexicographic
+    reverse search" vertex enumeration algorithm [1]_.
+
+    Parameters
+    ----------
+    g : NormalFormGame
+        2-player NormalFormGame instance with integer payoffs.
+
+    Returns
+    -------
+    NEs : list(tuple(ndarray(object, ndim=1)))
+        List containing tuples of Nash equilibrium mixed actions, where
+        the values are represented by `fractions.Fraction`.
+
+    Examples
+    --------
+    A degenerate game example:
+
+    >>> import quantecon.game_theory as gt
+    >>> import jlgametheory as jgt
+    >>> from pprint import pprint
+    >>> bimatrix = [[(3, 3), (3, 3)],
+    ...             [(2, 2), (5, 6)],
+    ...             [(0, 3), (6, 1)]]
+    >>> g = gt.NormalFormGame(bimatrix)
+    >>> NEs = jgt.lrsnash(g)
+    >>> pprint(NEs)
+    [(array([Fraction(1, 1), Fraction(0, 1), Fraction(0, 1)], dtype=object),
+      array([Fraction(1, 1), Fraction(0, 1)], dtype=object)),
+     (array([Fraction(1, 1), Fraction(0, 1), Fraction(0, 1)], dtype=object),
+      array([Fraction(2, 3), Fraction(1, 3)], dtype=object)),
+     (array([Fraction(0, 1), Fraction(1, 3), Fraction(2, 3)], dtype=object),
+      array([Fraction(1, 3), Fraction(2, 3)], dtype=object))]
+
+    The set of Nash equilibria of this degenerate game consists of an
+    isolated equilibrium, the third output, and a non-singleton
+    equilibrium component, the extreme points of which are given by the
+    first two outputs.
+
+    References
+    ----------
+    .. [1] D. Avis, G. Rosenberg, R. Savani, and B. von Stengel,
+       "Enumeration of Nash Equilibria for Two-Player Games," Economic
+       Theory (2010), 9-37.
+
+    """
+    try:
+        N = g.N
+    except AttributeError:
+        raise TypeError('input must be a 2-player NormalFormGame')
+    if N != 2:
+        raise NotImplementedError('Implemented only for 2-player games')
+    if not np.issubdtype(g.dtype, np.integer):
+        raise NotImplementedError(
+            'Implemented only for games with integer payoffs'
+        )
+
+    NEs_jl = GameTheory.lrsnash(to_jl_nfg(g))
+    return _to_py_nes(NEs_jl)
+
+
+def hc_solve(g, ntofind=float('inf'), **options):
+    """
+    Compute all isolated mixed-action Nash equilibria of an N-player
+    normal form game.
+
+    This function solves a system of polynomial equations arising from
+    the nonlinear complementarity problem representation of Nash
+    equilibrium, by using `HomotopyContinuation.jl`.
+
+    Parameters
+    ----------
+    g : NormalFormGame
+        N-player NormalFormGame instance.
+
+    ntofind : scalar, optional(default=float('inf'))
+        Number of Nash equilibria to find.
+
+    options :
+        Optional keyword arguments to pass to `HomotopyContinuation.solve`.
+        For example, the option `seed` can set the random seed used
+        during the computations. See the `documentation
+        <https://www.juliahomotopycontinuation.org/HomotopyContinuation.jl/stable/solve/>`_
+        for `HomotopyContinuation.solve` for details.
+
+    Returns
+    -------
+    NEs : list(tuple(ndarray(float, ndim=1)))
+        List containing tuples of Nash equilibrium mixed actions.
+
+    Examples
+    --------
+    Consider the 3-player 2-action game with 9 Nash equilibria in
+    McKelvey and McLennan (1996) "Computation of Equilibria in Finite
+    Games":
+
+    >>> import quantecon.game_theory as gt
+    >>> import jlgametheory as jgt
+    >>> from pprint import pprint
+    >>> import numpy as np
+    >>> np.set_printoptions(precision=3)  # Reduce the digits printed
+    >>> g = gt.NormalFormGame((2, 2, 2))
+    >>> g[0, 0, 0] = 9, 8, 12
+    >>> g[1, 1, 0] = 9, 8, 2
+    >>> g[0, 1, 1] = 3, 4, 6
+    >>> g[1, 0, 1] = 3, 4, 4
+    >>> print(g)
+    3-player NormalFormGame with payoff profile array:
+    [[[[ 9.,  8., 12.],   [ 0.,  0.,  0.]],
+      [[ 0.,  0.,  0.],   [ 3.,  4.,  6.]]],
+    <BLANKLINE>
+     [[[ 0.,  0.,  0.],   [ 3.,  4.,  4.]],
+      [[ 9.,  8.,  2.],   [ 0.,  0.,  0.]]]]
+    >>> NEs = jgt.hc_solve(g, show_progress=False)
+    >>> len(NEs)
+    9
+    >>> pprint(NEs)
+    [(array([0., 1.]), array([0., 1.]), array([1., 0.])),
+     (array([0.5, 0.5]), array([0.5, 0.5]), array([1.000e+00, 2.351e-38])),
+     (array([1., 0.]), array([0., 1.]), array([-1.881e-37,  1.000e+00])),
+     (array([0.25, 0.75]), array([0.5, 0.5]), array([0.333, 0.667])),
+     (array([0.25, 0.75]), array([1.000e+00, 1.345e-43]), array([0.25, 0.75])),
+     (array([0., 1.]), array([0.333, 0.667]), array([0.333, 0.667])),
+     (array([1., 0.]), array([ 1.00e+00, -5.74e-42]), array([1., 0.])),
+     (array([0., 1.]), array([1., 0.]), array([2.374e-66, 1.000e+00])),
+     (array([0.5, 0.5]), array([0.333, 0.667]), array([0.25, 0.75]))]
+    >>> all(g.is_nash(NE) for NE in NEs)
+    True
+
+    """
+    try:
+        N = g.N
+    except AttributeError:
+        raise TypeError('g must be a NormalFormGame')
+    if N < 2:
+        raise NotImplementedError('Not implemented for 1-player games')
+
+    NEs_jl = GameTheory.hc_solve(to_jl_nfg(g), ntofind=ntofind, **options)
+    return _to_py_nes(NEs_jl)

jlgametheory-0.1.0/jlgametheory/juliapkg.json

@@ -0,0 +1,9 @@
+{
+    "julia": "^1.6",
+    "packages": {
+        "GameTheory": {
+            "uuid": "64a4ffa8-f47c-4a47-8dad-aee7aadc3b51",
+            "version": "0.3.6"
+        }
+    }
+}

jlgametheory-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "jlgametheory"
+version = "0.1.0"
+description = "Python interface to GameTheory.jl"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    {name = "QuantEcon"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.22",
+    "quantecon>=0.8",
+    "juliacall>=0.9.20",
+]
+
+[project.optional-dependencies]
+# pip install jlgametheory[test]
+test = ["pytest>=7", "pytest-cov>=4"]
+# pip install jlgametheory[docs]
+docs = [
+    "sphinx>=8.0",
+    "sphinx-copybutton",
+]
+
+[project.urls]
+Homepage = "https://github.com/QuantEcon/jlgametheory"
+Repository = "https://github.com/QuantEcon/jlgametheory"
+
+[tool.coverage.run]
+omit = ["tests/test_*.py"]