[Catalog] Autogenerate game families

[edwardchalstrey1]

Pre-requisite: #753

This feature request is for...

PyGambit

Requested enahancement or feature

• Implement the option to have games from code with functions that take arguments to get variants of games. I previously started implementing this on Add Catalog of games #735
• Each game family can have it's own function that can be called with different parameters to get a set of similar games
• Linked to Implement bimatrix game generators #195 Implement polymatrix game generators #197

[edwardchalstrey1]

Code from #767 before we decided to backlog this for now:

In the catalog module, I added a function called family_games() which returns a dict of all games defined in code we want added to the catalog. This gives us the option to include as many variants of any family game functions as we want in the catalog. Then simply update the load function to include these alongside the games defined by EFG/NFG files.

def load(slug: str) -> gbt.Game:
   ...

    # Try loading from family games
    fg = family_games()
    if slug in fg:
        return fg[slug]


def family_games() -> dict[str, gbt.Game]:
    """
    Generate a dict of games for inclusion in the catalog,
    using the game families in this module.

    Returns
    -------
    dict[str, gbt.Game]
        A dictionary mapping slugs to game objects for family games.
    """
    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 [Kre90]_."
    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

[edwardchalstrey1]

To add to catalog dev docs:

Code new games & add game families

1. Add the game code:

   Open catalog/__init__.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/__init__.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.