Updating the Games Catalog#

This page covers the process for contributing to and updating Gambit’s Games 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 contributor guidelines.

You can add games to the catalog saved in a valid representation format, e.g. for .efg for extensive form games. Alternatively, you can define games for the catalog in pygambit code. You may wish to first review the pygambit docs pages.

Both options for adding to the catalog below include an optional step for adding metadata to the catalog for your game(s). Adding metadata to games will create a new filter for the pygambit.catalog.games() that users can search the catalog with.

Code games for the catalog

Write the pygambit code:

Write code for your game with pygambit. Your code should create a Game object with a title and description.

Note

Test your game by visualising it in draw_tree and running Gambit’s solvers.

Create a new Python class for your game:

Create a new branch in the gambit repo and open src/pygambit/catalog_games.py. Add a subclass of CatalogGame with your code implemented as the _game function, which should be defined as a staticmethod returning a Game object. You can optionally include paramaters to generate game variants.

class MyGame(gbt.catalog.CatalogGame):

    @staticmethod
    def _game(some_param: bool = False) -> gbt.Game:
        """
        Docstring for _game function.

        Parameters
        ----------
        some_param : bool, optional
            Description of optional paramater.
            Defaults to False.

        Returns
        -------
        gbt.Game
            The constructed game.

        Examples
        --------
        >>> MyGame(some_param=False) # Constructs the standard game
        >>> MyGame(some_param=True) # Constructs the alternate game
        """
        g = gbt.Game.new_tree(
            players=["Buyer", "Seller"], title="My game"
        )
        g.description = "Longer description of My game, originally by Author (2000)."
        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 some_param:
            g.set_outcome(
                g.root.children[0].children[1], g.add_outcome(["1/2", 2], label="Untrustworthy")
            )
        else:
            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

Note

If you add a docstring to the class itself, this will be used in the API reference docs as the game description instead of g.description

Update the catalog:

Use the catalog_update.py script to update the catalog and associated documatation & build files.
```
pip install ruamel.yaml
cd src/pygambit
python catalog_update.py
```
Note

Run this script in a Python environment where pygambit itself is also installed
[Optional] Add custom metadata to catalog games:

Open src/pygambit/catalog.py and add update the CatalogGame base class with the new metadata field. Include a type hint, a default value and a docstring.
```
# Metadata fields
my_metadata: int | None = None
"""Explanation of my_metadata field."""
```
Open src/pygambit/catalog_games.py and add a value for the field as a class attribute for the game(s) you added.
```
class MyGame(gbt.catalog.CatalogGame):
    my_metadata = 17
...
```

Submit a pull request to GitHub with all changes:

Warning

If you made changes in step 4 above, re-run the update script from step 3.

Warning

Make sure you commit all changed files e.g. run git add –all before committing and pushing.

Software tools for game theory.

Updating the Games Catalog#

This Page