[WIP] Add ability to have coded game families

.gitignore

@@ -50,3 +50,5 @@ Gambit.app/*
 *.ef
 build_support/msw/gambit.wxs
 build_support/osx/Info.plist
+src/pygambit/catalog
+doc/catalog.csv

.readthedocs.yml

@@ -13,9 +13,13 @@ build:
     - libgmp-dev
     - pandoc
     - texlive-full
+  jobs:
+    # Create CSV for catalog table in docs
+    post_install:
+      - $READTHEDOCS_VIRTUALENV_PATH/bin/python build_support/catalog/update.py
 
 python:
   install:
     - requirements: doc/requirements.txt
-    - method: setuptools
+    - method: pip
       path: "."

MANIFEST.in

@@ -1,6 +1,7 @@
 recursive-include src/core *.cc *.h *.imp
 recursive-include src/games *.cc *.h *.imp
 recursive-include src/solvers *.c *.cc *.h *.imp
+recursive-include catalog *
 include src/gambit.h
 include src/pygambit/*.pxd
 include src/pygambit/*.pyx

Makefile.am

@@ -101,7 +101,6 @@ EXTRA_DIST = \
 	src/gui/bitmaps/zoom1.xpm \
 	src/gui/bitmaps/gambitrc.rc \
 	contrib/games/2s2x2x2.efg \
-	contrib/games/2smp.efg \
 	contrib/games/2x2x2.efg \
 	contrib/games/4cards.efg \
 	contrib/games/artist1.efg \
@@ -169,7 +168,6 @@ EXTRA_DIST = \
 	contrib/games/my_3-3d.efg \
 	contrib/games/my_3-3e.efg \
 	contrib/games/my_3-4.efg \
-	contrib/games/myerson.efg \
 	contrib/games/nim7.efg \
 	contrib/games/nim.efg \
 	contrib/games/palf2.efg \
@@ -195,7 +193,6 @@ EXTRA_DIST = \
 	contrib/games/2x2a.nfg \
 	contrib/games/2x2const.nfg \
 	contrib/games/2x2.nfg \
-	contrib/games/2x2x2.nfg \
 	contrib/games/2x2x2x2.nfg \
 	contrib/games/2x2x2x2x2.nfg \
 	contrib/games/3x3x3.nfg \
@@ -224,7 +221,6 @@ EXTRA_DIST = \
 	contrib/games/mixdom2.nfg \
 	contrib/games/mixdom.nfg \
 	contrib/games/oneill.nfg \
-	contrib/games/pd.nfg \
 	contrib/games/perfect1.nfg \
 	contrib/games/perfect2.nfg \
 	contrib/games/perfect3.nfg \
@@ -240,7 +236,11 @@ EXTRA_DIST = \
 	contrib/games/winkels.nfg \
 	contrib/games/yamamoto.nfg \
 	contrib/games/zero.nfg \
-	src/README.rst
+	src/README.rst \
+	catalog/2smp.efg \
+	catalog/2x2x2.nfg \
+	catalog/myerson/fig_4_2.efg \
+	catalog/pd.nfg
 
 core_SOURCES = \
     src/core/core.h \

build_support/catalog/update.py

@@ -0,0 +1,74 @@
+import argparse
+from pathlib import Path
+
+import pygambit as gbt
+
+CATALOG_CSV = Path(__file__).parent.parent.parent / "doc" / "catalog.csv"
+CATALOG_DIR = Path(__file__).parent.parent.parent / "catalog"
+MAKEFILE_AM = Path(__file__).parent.parent.parent / "Makefile.am"
+
+
+def update_makefile():
+    """Update the Makefile.am with all games from the catalog."""
+
+    # Using rglob("*") to find files in all subdirectories
+    slugs = []
+    for resource_path in sorted(CATALOG_DIR.rglob("*.efg")):
+        if resource_path.is_file():
+            rel_path = resource_path.relative_to(CATALOG_DIR)
+            slugs.append(str(rel_path))
+    for resource_path in sorted(CATALOG_DIR.rglob("*.nfg")):
+        if resource_path.is_file():
+            rel_path = resource_path.relative_to(CATALOG_DIR)
+            slugs.append(str(rel_path))
+
+    game_files = []
+    for slug in slugs:
+        game_files.append(f"catalog/{slug}")
+    game_files.sort()
+
+    with open(MAKEFILE_AM, encoding="utf-8") as f:
+        content = f.readlines()
+
+    with open(MAKEFILE_AM, "w", encoding="utf-8") as f:
+        in_gamefiles_section = False
+        for line in content:
+            # Add to the EXTRA_DIST after the README.rst line
+            if line.startswith("	src/README.rst \\"):
+                in_gamefiles_section = True
+                f.write("	src/README.rst \\\n")
+                for gf in game_files:
+                    if gf == game_files[-1]:
+                        f.write(f"\t{gf}\n")
+                    else:
+                        f.write(f"\t{gf} \\\n")
+                f.write("\n")
+            elif in_gamefiles_section:
+                if line.strip() == "":
+                    in_gamefiles_section = False
+                continue  # Skip old gamefiles lines
+            else:
+                f.write(line)
+
+    with open(MAKEFILE_AM, encoding="utf-8") as f:
+        updated_content = f.readlines()
+
+    if content != updated_content:
+        print(f"Updated {str(MAKEFILE_AM)}")
+    else:
+        print(f"No changes to add to {str(MAKEFILE_AM)}")
+
+
+if __name__ == "__main__":
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--build", action="store_true")
+    args = parser.parse_args()
+
+    # Create CSV used by RST docs page
+    gbt.catalog.games().to_csv(CATALOG_CSV, index=False)
+    print(f"Generated {CATALOG_CSV} for use in local docs build. DO NOT COMMIT.")
+
+    # Update the Makefile.am with the current list of catalog files
+    if args.build:
+        update_makefile()

catalog/__init__.py

@@ -0,0 +1,6 @@
+from .utils import games, load
+
+__all__ = [
+    "load",
+    "games",
+]

catalog/families.py

@@ -0,0 +1,54 @@
+
+import pygambit as gbt
+
+
+def family_games() -> dict[str, gbt.Game]:
+    """
+    Generate a dict of games for inclusion in the catalog,
+    using the game families in this module.
+    """
+    return {
+        "one_shot_trust": one_shot_trust(),
+        "oneshot_trust_unique_NE": one_shot_trust(unique_NE_variant=True),
+    }
+
+
+################################################################################################
+# Families
+
+def one_shot_trust(unique_NE_variant: bool = False) -> gbt.Game:
+    """
+    The unique_NE_variant makes Trust a dominant strategy, replacing the
+    non-singleton equilibrium component from the standard version of the game
+    where the Buyer plays "Not Trust" and the seller can play any mixture with
+    < 0.5 probability on Honor with a unique NE where the Buyer plays Trust and
+    the Seller plays Abuse.
+
+    Parameters
+    ----------
+    unique_NE_variant : bool, optional
+        Whether to modify the game so that it has a unique Nash equilibrium.
+        Defaults to False.
+
+    Returns
+    -------
+    gbt.Game
+        The constructed extensive-form game.
+    """
+    g = gbt.Game.new_tree(players=["Buyer", "Seller"])
+    g.description = "One-shot trust game with binary actions, originally from Kreps (1990)."
+    g.append_move(g.root, "Buyer", ["Trust", "Not trust"])
+    g.append_move(g.root.children[0], "Seller", ["Honor", "Abuse"])
+    g.set_outcome(g.root.children[0].children[0], g.add_outcome([1, 1], label="Trustworthy"))
+    if unique_NE_variant:
+        g.title = "One-shot trust game with unique NE"
+        g.set_outcome(
+            g.root.children[0].children[1], g.add_outcome(["1/2", 2], label="Untrustworthy")
+        )
+    else:
+        g.title = "One-shot trust game"
+        g.set_outcome(
+            g.root.children[0].children[1], g.add_outcome([-1, 2], label="Untrustworthy")
+        )
+    g.set_outcome(g.root.children[1], g.add_outcome([0, 0], label="Opt-out"))
+    return g

catalog/utils.py

@@ -0,0 +1,75 @@
+from importlib.resources import as_file, files
+from pathlib import Path
+
+import pandas as pd
+
+import pygambit as gbt
+
+from .families import family_games
+
+# Use the full string path to the virtual package we created
+_CATALOG_RESOURCE = files(__name__)
+
+READERS = {
+    ".nfg": gbt.read_nfg,
+    ".efg": gbt.read_efg,
+}
+
+
+def load(slug: str) -> gbt.Game:
+    """
+    Load a game from the package catalog.
+    """
+    slug = str(Path(slug)).replace("\\", "/")
+
+    # Try to load from file
+    for suffix, reader in READERS.items():
+        resource_path = _CATALOG_RESOURCE / f"{slug}{suffix}"
+        if resource_path.is_file():
+            with as_file(resource_path) as path:
+                return reader(str(path))
+
+    # Try loading from family games
+    fg = family_games()
+    if slug in fg:
+        return fg[slug]
+
+    # Raise error if game does not exist
+    raise FileNotFoundError(f"No catalog entry called {slug}")
+
+
+def games() -> pd.DataFrame:
+    """
+    List games available in the package catalog, including subdirectories.
+    """
+    records: list[dict[str, str]] = []
+
+    # Add all the games stored as EFG/NFG files
+    for resource_path in sorted(_CATALOG_RESOURCE.rglob("*")):
+        reader = READERS.get(resource_path.suffix)
+
+        if reader is not None and resource_path.is_file():
+            # Calculate the path relative to the root resource
+            # and remove the suffix to get the "slug"
+            rel_path = resource_path.relative_to(_CATALOG_RESOURCE)
+            slug = rel_path.with_suffix("").as_posix()
+
+            with as_file(resource_path) as path:
+                game = reader(str(path))
+                records.append(
+                    {
+                        "Game": slug,
+                        "Title": game.title,
+                    }
+                )
+
+    # Add all the games from families
+    for slug, game in family_games().items():
+        records.append(
+            {
+                "Game": slug,
+                "Title": game.title,
+            }
+        )
+
+    return pd.DataFrame.from_records(records, columns=["Game", "Title"])

doc/catalog.rst

@@ -0,0 +1,8 @@
+Catalog of games
+================
+
+.. csv-table::
+   :file: catalog.csv
+   :header-rows: 1
+   :widths: 20, 80
+   :class: tight-table

doc/developer.catalog.rst

@@ -0,0 +1,60 @@
+Updating the Games Catalog
+==========================
+
+This page covers the process for contributing to and updating Gambit's :ref:`Games Catalog <pygambit-catalog>`.
+To do so, you will need to have the `gambit` GitHub repo cloned and be able to submit pull request via GitHub;
+you may wish to first review the :ref:`contributor guidelines <contributing>`.
+
+You can add games to the catalog saved in a valid representation :ref:`format <file-formats>`.
+Currently supported representations are:
+
+- `.efg` for extensive form games
+- `.nfg` for normal form games
+
+Add new game files
+------------------
+
+1. **Create the game file:**
+
+   Use either :ref:`pygambit <pygambit>`, the Gambit :ref:`CLI <command-line>` or :ref:`GUI <section-gui>` to create and save game in a valid representation :ref:`format <file-formats>`.
+
+2. **Add the game file:**
+
+   Create a new branch in the ``gambit`` repo. Add your new game file(s) inside the ``catalog`` dir and commit them.
+
+3. **Update the catalog:**
+
+   Use the ``update.py`` script to update Gambit's documentation & build files.
+
+   .. code-block:: bash
+
+       python build_support/catalog/update.py --build
+
+   .. note::
+
+      Run this script in a Python environment where ``pygambit`` itself is also :ref:`installed <build-python>`.
+
+   .. warning::
+
+      Running the script with the ``--build`` flag updates `Makefile.am`. If you moved games that were previously in `contrib/games` you'll need to also manually remove those files from `EXTRA_DIST`.
+
+4. **Submit a pull request to GitHub with all changes.**
+
+   .. warning::
+
+      Make sure you commit all changed files e.g. run ``git add --all`` before committing and pushing.
+
+Code new games & add game families
+----------------------------------
+
+1. **Add the game code:**
+
+   Open `catalog/families.py` and create a new function, or modify an existing one. Ensure your function returns a ``Game`` object.
+   You may wish to vary the game title and/or description based on the chosen parameters.
+
+2. **Update the catalog:**
+
+   Update the dictionary returned by ``family_games()`` in `catalog/families.py` with all variants of your game(s) you want in the catalog.
+   Ensure each entry has unique game slug as key (this will be used by ``pygambit.catalog.load('slug')``), and returns a call of the function with specific parameters.
+
+3. **Submit a pull request to GitHub with all changes.**

doc/developer.contributing.rst

@@ -1,3 +1,5 @@
+.. _contributing:
+
 Contributing to Gambit
 ======================
 

doc/developer.rst

@@ -11,3 +11,4 @@ This section contains information for developers who want to contribute to the G
 
    developer.build
    developer.contributing
+   developer.catalog

doc/index.rst

@@ -64,6 +64,7 @@ We recommended most new users install the PyGambit Python package and read the a
    pygambit
    tools
    gui
+   catalog
    samples
    developer
    formats