Add EFGs from Shoham and Leyton-Brown (2008)

.github/workflows/python.yml

@@ -30,7 +30,7 @@ jobs:
           cd dist
           sdist=$(ls pygambit-*.tar.gz)
           pip install -v "${sdist}[test,doc]"
-          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.9.1"
+          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.11.0"
       - name: Run tests
         run: pytest --run-tutorials
 
@@ -53,7 +53,7 @@ jobs:
       - name: Build extension
         run: |
           python -m pip install -v .[test,doc]
-          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.9.1"
+          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.11.0"
       - name: Run tests
         run: pytest --run-tutorials
 
@@ -76,7 +76,7 @@ jobs:
       - name: Build extension
         run: |
           python -m pip install -v .[test,doc]
-          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.9.1"
+          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.11.0"
       - name: Run tests
         run: pytest --run-tutorials
 
@@ -99,6 +99,6 @@ jobs:
       - name: Build extension
         run: |
           python -m pip install -v .[test,doc]
-          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.9.1"
+          pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.11.0"
       - name: Run tests
         run: pytest --run-tutorials

.readthedocs.yml

@@ -17,7 +17,7 @@ build:
     - pdf2svg
   jobs:
     post_install:
-      - pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.9.1"
+      - pip install "draw-tree @ git+https://github.com/gambitproject/draw_tree.git@v0.11.0"
       # Create RST for catalog table in docs
       - $READTHEDOCS_VIRTUALENV_PATH/bin/python build_support/catalog/update.py
 

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/draw_tree_settings.yaml

@@ -31,3 +31,60 @@ overrides:
     sublevel_scaling: 0.5
   journals/geb/gilboa1997/fig1:
     action_label_dist: 5.0
+  books/shohambrown2008/fig5_12:
+    action_label_dist: 5.0
+    width_scaling: 0.75
+  books/shohambrown2008/fig6_2:
+    action_label_dist: 5.0
+  books/shohambrown2008/fig6_8:
+    sublevel_scaling: 1
+    action_label_dist: 5.0
+  books/bonanno18/fig12_18:
+    scale_factor: 1.0
+    level_scaling: 1.0
+    sublevel_scaling: 1.0
+    width_scaling: 2.0
+    shared_terminal_depth: false
+    action_label_position_by: player
+    action_label_dist: 1.5
+    vary_action_label_positions: true
+    vary_action_label_positions_by: player
+    label_bg:
+      3: true
+    label_bg_opacity: 0.8
+    vary_action_label_positions_choices:
+    - 3
+  books/bonanno18/fig3_10:
+    width_scaling: 1.6
+  books/bonanno18/fig3_17:
+    action_label_position: 0.8
+  books/bonanno18/fig4_17:
+    sublevel_scaling: 1.0
+    action_label_position: 0.35
+    width_scaling: 1.25
+  books/bonanno18/fig4_19:
+    sublevel_scaling: 0
+    shared_terminal_depth: true
+    action_label_position_by: player
+    label_bg:
+      0: true
+    label_bg_color: white
+    label_bg_opacity: 0.8
+  books/bonanno18/fig4_3:
+    sublevel_scaling: 0.5
+    width_scaling: 1.25
+    action_label_position_by: player
+    vary_action_label_positions: true
+    vary_action_label_positions_by: player
+    label_bg:
+      3: true
+    vary_action_label_positions_choices:
+    - 3
+  books/bonanno18/fig4_40:
+    sublevel_scaling: 1
+    shared_terminal_depth: true
+    action_label_position_by: player
+    label_bg:
+      0: true
+    label_bg_color: white
+    label_bg_opacity: 0.8

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 local_catalog == update.gbt.catalog._CATALOG_RESOURCE
+
+
 # ---------------------------------------------------------------------------
 # Tests for catalog_draw_tree_settings
 # ---------------------------------------------------------------------------

build_support/catalog/update.py

@@ -17,6 +17,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:
@@ -408,11 +419,18 @@ 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)
     _warn_missing_descriptions(df)
-    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 }