[Catalog] Autogenerate game families #758

Activity

1. edwardchalstrey1

   added

   enhancement

   catalogIssues that relate to the Gambit's Catalog of gamesIssues that relate to the Gambit's Catalog of games

   on Feb 5, 2026
2. edwardchalstrey1

   self-assigned this

   on Feb 5, 2026
3. edwardchalstrey1

   added a parent issue on Feb 5, 2026

   • MAP: Catalog of standard games/game generators #394
4. edwardchalstrey1 commented on Mar 24, 2026

   

   edwardchalstrey1

   on Mar 24, 2026

   MemberAuthor

   More actions

   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
5. edwardchalstrey1 commented on Mar 24, 2026

   

   edwardchalstrey1

   on Mar 24, 2026

   MemberAuthor

   More actions

   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.
6. edwardchalstrey1

   removed their assignment

   on Jun 25, 2026