Add EFGs from Shoham and Leyton-Brown (2008)

build_support/catalog/catalog.am

@@ -1,6 +1,25 @@
 CATALOG_FILES = \
+	catalog/books/bonanno18/fig12_18.efg \
+	catalog/books/bonanno18/fig3_1.efg \
+	catalog/books/bonanno18/fig3_10.efg \
+	catalog/books/bonanno18/fig3_17.efg \
+	catalog/books/bonanno18/fig4_17.efg \
+	catalog/books/bonanno18/fig4_19.efg \
+	catalog/books/bonanno18/fig4_26.efg \
+	catalog/books/bonanno18/fig4_3.efg \
+	catalog/books/bonanno18/fig4_40.efg \
+	catalog/books/bonanno18/fig4_5.efg \
 	catalog/books/myerson1991/fig2_1.efg \
 	catalog/books/myerson1991/fig4_2.efg \
+	catalog/books/shohambrown2008/fig5_1.efg \
+	catalog/books/shohambrown2008/fig5_10.efg \
+	catalog/books/shohambrown2008/fig5_11.efg \
+	catalog/books/shohambrown2008/fig5_12.efg \
+	catalog/books/shohambrown2008/fig5_15.efg \
+	catalog/books/shohambrown2008/fig5_2.efg \
+	catalog/books/shohambrown2008/fig5_9.efg \
+	catalog/books/shohambrown2008/fig6_2.efg \
+	catalog/books/shohambrown2008/fig6_8.efg \
 	catalog/books/vonstengel2022/fig10.1.efg \
 	catalog/books/vonstengel2022/fig10.12.efg \
 	catalog/books/vonstengel2022/fig10.5.efg \

build_support/catalog/catalog_hierarchy.yaml

@@ -14,6 +14,8 @@ labels:
   books/myerson1991: "Myerson (1991) — Game Theory: Analysis of Conflict"
   books/vonstengel2022: "von Stengel (2022) — Game Theory Basics"
   books/watson2013: "Watson (2013) — Strategy: An Introduction to Game Theory"
+  books/shohambrown2008: "Shoham and Leyton-Brown (2008) — Multiagent Systems, Algorithmic, Game-Theoretic, and Logical Foundations"
+  books/bonanno18: "Giacomo Bonanno (2018) — Game Theory"
   journals/geb/gilboa1997: "Gilboa (1997)"
   journals/geb/wichardt2008: "Wichardt (2008)"
   journals/ijgt/nau2004: "Nau et al. (2004)"

build_support/catalog/test_update.py

@@ -147,6 +147,27 @@ def _make_image_files(catalog_dir, slug, fmt="efg"):
         (img_dir / f"{slug}.ef").touch()
 
 
+# ---------------------------------------------------------------------------
+# Tests for catalog resource selection
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.catalog_update
+class TestCatalogResourceSelection:
+    """Tests for selecting the catalog source used by update.py."""
+
+    def test_use_catalog_dir_overrides_stale_package_catalog(self, tmp_path, monkeypatch):
+        """The updater points pygambit's catalog helpers at the local catalog dir."""
+        stale_catalog = tmp_path / "stale_catalog_data"
+        local_catalog = tmp_path / "catalog"
+        monkeypatch.setattr(update.gbt.catalog, "_CATALOG_RESOURCE", stale_catalog)
+
+        selected = update.use_catalog_dir(local_catalog)
+
+        assert selected == local_catalog
+        assert update.gbt.catalog._CATALOG_RESOURCE == local_catalog
+
+
 # ---------------------------------------------------------------------------
 # Tests for catalog_draw_tree_settings
 # ---------------------------------------------------------------------------

build_support/catalog/update.py

@@ -16,6 +16,17 @@
 SUPPORTED_GAME_FORMATS = {"efg", "nfg"}
 
 
+def use_catalog_dir(catalog_dir: Path | None = None) -> Path:
+    """Point pygambit's catalog helpers at this checkout's catalog directory.
+
+    update.py is a source-tree maintenance script, so it should not read stale
+    package-data copies from an installed or previously built pygambit.
+    """
+    catalog_dir = catalog_dir or CATALOG_DIR
+    gbt.catalog._CATALOG_RESOURCE = catalog_dir
+    return catalog_dir
+
+
 def catalog_draw_tree_settings(slug: str) -> dict:
     """Return the draw_tree settings for a given catalog slug."""
     with open(DRAW_TREE_SETTINGS_CONFIG, encoding="utf-8") as f:
@@ -390,10 +401,17 @@ def update_makefile(
     )
     args = parser.parse_args()
 
+    catalog_dir = use_catalog_dir()
+
     # Create RST list-table used by doc/catalog.rst
     df = gbt.catalog.games(include_descriptions=True)
-    generate_rst_table(df, CATALOG_RST_TABLE, regenerate_images=args.regenerate_images)
+    generate_rst_table(
+        df,
+        CATALOG_RST_TABLE,
+        regenerate_images=args.regenerate_images,
+        catalog_dir=catalog_dir,
+    )
     print(f"Generated {CATALOG_RST_TABLE} for use in local docs build. DO NOT COMMIT.")
     if args.build:
         # Update the Makefile.am with the current list of catalog files
-        update_makefile()
+        update_makefile(catalog_dir=catalog_dir)

catalog/books/bonanno18/fig12_18.efg

@@ -0,0 +1,23 @@
+EFG 2 R "Fig 12.18 from Bonanno (2018)" { "Player 1" "Player 2" "Player 3" }
+"
+Fig 12.18 from :cite:p:`Gia18`.
+
+This is a game from exercise 12.5. 
+"
+
+p "" 1 1 "" { "Off" "On" } 0
+p "" 2 1 "" { "Off" "On" } 0
+p "" 3 1 "" { "Guess (Off,Off)" "Guess (Off,On)" "Guess (On,Off)" } 0
+t "" 1 "All 200 (correct guess)" { 200, 200, 200 }
+t "" 2 "P1 correct, P2 wrong, P3 gets 50" { 100, 0, 50 }
+t "" 3 "P2 correct, P1 wrong, P3 gets 50" { 0, 100, 50 }
+p "" 3 1 "" { "Guess (Off,Off)" "Guess (Off,On)" "Guess (On,Off)" } 0
+t "" 2 "P1 correct, P2 wrong, P3 gets 50" { 100, 0, 50 }
+t "" 1 "All 200 (correct guess)" { 200, 200, 200 }
+t "" 4 "All 0 (guess entirely wrong)" { 0, 0, 0 }
+p "" 2 1 "" { "Off" "On" } 0
+p "" 3 1 "" { "Guess (Off,Off)" "Guess (Off,On)" "Guess (On,Off)" } 0
+t "" 3 "P2 correct, P1 wrong, P3 gets 50" { 0, 100, 50 }
+t "" 4 "All 0 (guess entirely wrong)" { 0, 0, 0 }
+t "" 1 "All 200 (correct guess)" { 200, 200, 200 }
+t "" 5 "Both On -> immediate payoffs" { 100, 100, 300 }

catalog/books/bonanno18/fig3_1.efg

@@ -0,0 +1,14 @@
+EFG 2 R "Fig 3.1 from Bonanno (2018)" { "Amy" "Beth" }
+"
+Fig 3.1 from :cite:p:`Gia18`.
+
+This is an ultimatum game. 
+"
+
+p "" 1 1 "" { "50-50" "70-30" } 0
+p "" 2 1 "" { "Accept" "Reject" } 0
+t "" 1 "50-50 Accept" { 50000, 50000 }
+t "" 2 "Litigation" { 40000, 20000 }
+p "" 2 2 "" { "Accept" "Reject" } 0
+t "" 3 "70-30 Accept" { 70000, 30000 }
+t "" 2 "Litigation" { 40000, 20000 }

catalog/books/bonanno18/fig3_10.efg

@@ -0,0 +1,12 @@
+EFG 2 R "Fig 3.10 from Bonanno (2018)" { "Entrant" "Incumbent" }
+"
+Fig 3.10 from :cite:p:`Gia18`.
+
+This is a market entry game. 
+"
+
+p "" 1 1 "" { "Enter" "Stay out" } 0
+p "" 2 1 "" { "Fight" "Accommodate" } 0
+t "" 2 "Fight (both 0)" { 0, 0 }
+t "" 3 "Accommodate (both 2)" { 2, 2 }
+t "" 1 "Stay out (Entrant=1, Incumbent=5)" { 1, 5 }

catalog/books/bonanno18/fig3_17.efg

@@ -0,0 +1,26 @@
+EFG 2 R "Fig 3.17 from Bonanno (2018)" { "A" "B" "C" }
+"
+Fig 3.17 from :cite:p:`Gia18`.
+
+This is a board voting game from exercise 3.2. 
+"
+
+p "" 1 1 "" { "Promote" "Keep" "Fire" } 0
+p "" 2 1 "" { "Accept" "Disagree" } 0
+t "" 1 "Promote" { 3, 1, 2 }
+p "" 3 1 "" { "Promote" "Keep" "Fire" } 0
+t "" 1 "Promote" { 3, 1, 2 }
+t "" 2 "Keep" { 2, 3, 1 }
+t "" 3 "Fire" { 1, 2, 3 }
+p "" 2 2 "" { "Accept" "Disagree" } 0
+t "" 2 "Keep" { 2, 3, 1 }
+p "" 3 2 "" { "Promote" "Keep" "Fire" } 0
+t "" 1 "Promote" { 3, 1, 2 }
+t "" 2 "Keep" { 2, 3, 1 }
+t "" 3 "Fire" { 1, 2, 3 }
+p "" 2 3 "" { "Accept" "Disagree" } 0
+t "" 3 "Fire" { 1, 2, 3 }
+p "" 3 3 "" { "Promote" "Keep" "Fire" } 0
+t "" 1 "Promote" { 3, 1, 2 }
+t "" 2 "Keep" { 2, 3, 1 }
+t "" 3 "Fire" { 1, 2, 3 }

catalog/books/bonanno18/fig4_17.efg

@@ -0,0 +1,22 @@
+EFG 2 R "Fig 4.17 from Bonanno (2018)" { "Adele" "Ben" }
+"
+Fig 4.17 from :cite:p:`Gia18`.
+
+This is an example for chance moves in EFGs. 
+"
+
+c "" 1 "" { "Black" 1/3 "Red" 2/3 } 0
+p "" 1 1 "" { "Say Black" "Say Red" } 0
+p "" 2 1 "" { "Guess Black" "Guess Red" } 0
+t "" 1 "Ben correct" { -9, 9 }
+t "" 2 "Ben incorrect" { 9, -9 }
+p "" 2 2 "" { "Guess Black" "Guess Red" } 0
+t "" 1 "Ben correct" { -9, 9 }
+t "" 2 "Ben incorrect" { 9, -9 }
+p "" 1 2 "" { "Say Black" "Say Red" } 0
+p "" 2 1 "" { "Guess Black" "Guess Red" } 0
+t "" 2 "Ben incorrect" { 9, -9 }
+t "" 1 "Ben correct" { -9, 9 }
+p "" 2 2 "" { "Guess Black" "Guess Red" } 0
+t "" 2 "Ben incorrect" { 9, -9 }
+t "" 1 "Ben correct" { -9, 9 }

catalog/books/bonanno18/fig4_19.efg

@@ -0,0 +1,38 @@
+EFG 2 R "Fig 4.19 from Bonanno (2018)" { "Player 1" "Player 2" }
+"
+Fig 4.19 from :cite:p:`Gia18`.
+
+This is a game where two players decide whether to exchange envelopes that contain money. 
+"
+
+c "" 1 "" { "P1:100 P2:200" 1/6 "P1:100 P2:300" 1/6 "P1:200 P2:100" 1/6 "P1:200 P2:300" 1/6 "P1:300 P2:100" 1/6 "P1:300 P2:200" 1/6 } 0
+p "" 1 1 "" { "Pass" "Request trade" } 0
+t "" 1 "P1 keeps 100, P2 keeps 200" { 100, 200 }
+p "" 2 1 "" { "Yes" "No" } 0
+t "" 2 "Traded: P1 200, P2 100" { 200, 100 }
+t "" 1 "P1 keeps 100, P2 keeps 200" { 100, 200 }
+p "" 1 1 "" { "Pass" "Request trade" } 0
+t "" 3 "P1 keeps 100, P2 keeps 300" { 100, 300 }
+p "" 2 1 "" { "Yes" "No" } 0
+t "" 4 "Traded: P1 300, P2 100" { 300, 100 }
+t "" 3 "P1 keeps 100, P2 keeps 300" { 100, 300 }
+p "" 1 2 "" { "Pass" "Request trade" } 0
+t "" 5 "P1 keeps 200, P2 keeps 100" { 200, 100 }
+p "" 2 1 "" { "Yes" "No" } 0
+t "" 6 "Traded: P1 100, P2 200" { 100, 200 }
+t "" 5 "P1 keeps 200, P2 keeps 100" { 200, 100 }
+p "" 1 2 "" { "Pass" "Request trade" } 0
+t "" 7 "P1 keeps 200, P2 keeps 300" { 200, 300 }
+p "" 2 1 "" { "Yes" "No" } 0
+t "" 8 "Traded: P1 300, P2 200" { 300, 200 }
+t "" 7 "P1 keeps 200, P2 keeps 300" { 200, 300 }
+p "" 1 3 "" { "Pass" "Request trade" } 0
+t "" 9 "P1 keeps 300, P2 keeps 100" { 300, 100 }
+p "" 2 1 "" { "Yes" "No" } 0
+t "" 10 "Traded: P1 100, P2 300" { 100, 300 }
+t "" 9 "P1 keeps 300, P2 keeps 100" { 300, 100 }
+p "" 1 3 "" { "Pass" "Request trade" } 0
+t "" 11 "P1 keeps 300, P2 keeps 200" { 300, 200 }
+p "" 2 1 "" { "Yes" "No" } 0
+t "" 12 "Traded: P1 200, P2 300" { 200, 300 }
+t "" 11 "P1 keeps 300, P2 keeps 200" { 300, 200 }

catalog/books/bonanno18/fig4_26.efg

@@ -0,0 +1,23 @@
+EFG 2 R "Fig 4.26 from Bonanno (2018)" { "Amy" "Bill" }
+"
+Fig 4.26 from :cite:p:`Gia18`.
+
+This is a simple auction where two players bid on a piece of paper. 
+We add the value of the object, which is not specified in the original description, since this is necessary for determining payoffs.
+"
+
+p "" 1 1 "" { "2" "3" } 0
+p "" 2 1 "" { "2" "3" } 0
+p "" 1 2 "" { "Pass" "Double" } 0
+t "" 1 "A2_B2_Pass" { 0, 8 }
+t "" 2 "A4_B2_Double" { 6, 0 }
+p "" 1 2 "" { "Pass" "Double" } 0
+t "" 3 "A2_B3_Pass" { 0, 7 }
+t "" 4 "A4_B3_Double" { 6, 0 }
+p "" 2 1 "" { "2" "3" } 0
+p "" 1 3 "" { "Pass" "Double" } 0
+t "" 5 "A3_B2_Pass" { 7, 0 }
+t "" 6 "A6_B2_Double" { 4, 0 }
+p "" 1 4 "" { "Pass" "Double" } 0
+t "" 7 "A3_B3_Pass" { 0, 7 }
+t "" 8 "A6_B3_Double" { 4, 0 }

catalog/books/bonanno18/fig4_3.efg

@@ -0,0 +1,22 @@
+EFG 2 R "Fig 4.3 from Bonanno (2018)" { "Ann" "Bob" "Carla" }
+"
+Fig 4.3 from :cite:p:`Gia18`.
+
+This is an example of imperfect-information games to explain information sets. 
+"
+
+p "" 1 1 "" { "Red" "Black" } 0
+p "" 2 1 "" { "Say Red" "Say Black" } 0
+p "" 3 1 "" { "Guess Red" "Guess Black" } 0
+t "" 1 "Carla correct" { -1, -1, 2 }
+t "" 2 "Carla incorrect" { 1, 1, -2 }
+p "" 3 2 "" { "Guess Red" "Guess Black" } 0
+t "" 1 "Carla correct" { -1, -1, 2 }
+t "" 2 "Carla incorrect" { 1, 1, -2 }
+p "" 2 2 "" { "Say Red" "Say Black" } 0
+p "" 3 1 "" { "Guess Red" "Guess Black" } 0
+t "" 2 "Carla incorrect" { 1, 1, -2 }
+t "" 1 "Carla correct" { -1, -1, 2 }
+p "" 3 2 "" { "Guess Red" "Guess Black" } 0
+t "" 2 "Carla incorrect" { 1, 1, -2 }
+t "" 1 "Carla correct" { -1, -1, 2 }

catalog/books/bonanno18/fig4_40.efg

@@ -0,0 +1,38 @@
+EFG 2 R "Fig 4.40 from Bonanno (2018)" { "Yvonne" "Zoe" }
+"
+Fig 4.40 from :cite:p:`Gia18`.
+
+This is a simplified poker game. 
+"
+
+c "" 1 "" { "Y:A,Z:B" 1/6 "Y:A,Z:C" 1/6 "Y:B,Z:A" 1/6 "Y:B,Z:C" 1/6 "Y:C,Z:A" 1/6 "Y:C,Z:B" 1/6 } 0
+p "" 1 1 "" { "Pass" "Bet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+p "" 2 1 "" { "Fold" "Meet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+t "" 2 "Yvonne wins big" { 2, -2 }
+p "" 1 1 "" { "Pass" "Bet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+p "" 2 2 "" { "Fold" "Meet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+t "" 2 "Yvonne wins big" { 2, -2 }
+p "" 1 2 "" { "Pass" "Bet" } 0
+t "" 3 "Zoe wins small" { -1, 1 }
+p "" 2 3 "" { "Fold" "Meet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+t "" 4 "Zoe wins big" { -2, 2 }
+p "" 1 2 "" { "Pass" "Bet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+p "" 2 2 "" { "Fold" "Meet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+t "" 2 "Yvonne wins big" { 2, -2 }
+p "" 1 3 "" { "Pass" "Bet" } 0
+t "" 3 "Zoe wins small" { -1, 1 }
+p "" 2 3 "" { "Fold" "Meet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+t "" 4 "Zoe wins big" { -2, 2 }
+p "" 1 3 "" { "Pass" "Bet" } 0
+t "" 3 "Zoe wins small" { -1, 1 }
+p "" 2 1 "" { "Fold" "Meet" } 0
+t "" 1 "Yvonne wins small" { 1, -1 }
+t "" 4 "Zoe wins big" { -2, 2 }

catalog/books/bonanno18/fig4_5.efg

@@ -0,0 +1,18 @@
+EFG 2 R "Fig 4.5 from Bonanno (2018)" { "Employer" "Yvonne" "Fran" }
+"
+Fig 4.5 from :cite:p:`Gia18`.
+
+This is a game where two players interview for the same job. Only one person will be hired. 
+"
+
+p "" 1 1 "" { "Call Yvonne" "Call Fran" } 0
+p "" 2 1 "" { "Accept" "Reject" } 0
+t "" 1 "Yvonne accepts first" { 1, 2, 1 }
+p "" 3 1 "" { "Accept" "Reject" } 0
+t "" 2 "Fran accepts recycled" { 1, 1, 0 }
+t "" 3 "Both reject (unfilled)" { 0, 1, 1 }
+p "" 3 1 "" { "Accept" "Reject" } 0
+t "" 4 "Fran accepts first" { 1, 1, 2 }
+p "" 2 1 "" { "Accept" "Reject" } 0
+t "" 5 "Yvonne accepts recycled" { 1, 0, 1 }
+t "" 3 "Both reject (unfilled)" { 0, 1, 1 }

catalog/books/shohambrown2008/fig5_1.efg

@@ -0,0 +1,21 @@
+EFG 2 R "Fig 5.1 from Shoham and Leyton-Brown (2008)" { "1" "2" }
+
+"
+Figure 5.1 from :cite:p:`ShoLeyB08`.
+This is a sharing game. Imagine a brother and sister sharing two indivisible and identical presents
+from their parents. First the brother suggests a split, which can be one of three-he
+keeps both, she keeps both, or they each keep one. Then the sister chooses whether
+to accept or reject the split. If she accepts they each get their allocated present(s),
+and otherwise neither gets any gift.
+"
+
+p "" 1 1 "" { "2-0" "1-1" "0-2" } 0
+p "" 2 2 "" { "no" "yes" } 0
+t "" 1 "" { 0 0 }
+t "" 2 "" { 2 0 }
+p "" 2 3 "" { "no" "yes" } 0
+t "" 3 "" { 0 0 }
+t "" 4 "" { 1 1 }
+p "" 2 4 "" { "no" "yes" } 0
+t "" 5 "" { 0 0 }
+t "" 6 "" { 0 2 }

catalog/books/shohambrown2008/fig5_10.efg

@@ -0,0 +1,16 @@
+EFG 2 R "Fig 5.10 from Shoham and Leyton-Brown (2008)" { "1" "2" }
+
+"
+Figure 5.10 from :cite:p:`ShoLeyB08`.
+This is an example of an imperfect-information game.
+"
+
+p "" 1 2 "" { "L" "R" } 0
+p "" 2 3 "" { "A" "B" } 0
+p "" 1 1 "" { "l" "r" } 0
+t "" 1 "" { 0 0 }
+t "" 2 "" { 2 4 }
+p "" 1 1 0
+t "" 3 "" { 4 2 }
+t "" 4 "" { 0 0 }
+t "" 5 "" { 0 0 }