Skip to content

Enforce unique, nonempty labels for outcomes #982

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tturocy merged 6 commits into from
Jul 10, 2026
Merged

Enforce unique, nonempty labels for outcomes #982

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9cdfbaf
Enforce unique, nonempty labels for outcomes
d-kad Jul 8, 2026
8566773
Add generation of admissible outcome labels in GUI
tturocy Jul 9, 2026
9f4c664
Normalize outcome labels from game files before creating outcomes
d-kad Jul 10, 2026
0afe25f
Add tests for outcome label handling
d-kad Jul 10, 2026
8bbc6d0
Make outcome label genuinely required for `add_outcome` (having an op…
tturocy Jul 10, 2026
5765816
Update tutorials for new signature of `add_outcome`
tturocy Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 54 additions & 21 deletions doc/tutorials/02_extensive_form.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,42 @@
"cell_type": "markdown",
"id": "96019084",
"metadata": {},
"source": "# 2) Extensive-form games\n\nIn the first tutorial, we used Gambit to set up the Prisoner's Dilemma, an example of a normal (strategic) form game.\n\nGambit can also be used to set up extensive-form games; the game is represented as a tree, where each node represents a decision point for a player, and the branches represent the possible actions they can take.\n\n**Example: One-shot trust game with binary actions**\n\n[Kreps (1990)](#references) introduced a game commonly referred to as the **trust game**.\nWe will build a one-shot version of this game using Gambit's game transformation operations.\n\nThe game can be defined as follows:\n- There are two players, a **Buyer** and a **Seller**.\n- The Buyer moves first and has two actions, **Trust** or **Not trust**.\n- If the Buyer chooses **Not trust**, then the game ends, and both players receive payoffs of `0`.\n- If the Buyer chooses **Trust**, then the Seller has a choice with two actions, **Honor** or **Abuse**.\n- If the Seller chooses **Honor**, both players receive payoffs of `1`;\n- If the Seller chooses **Abuse**, the Buyer receives a payoff of `-1` and the Seller receives a payoff of `2`.\n\nIn addition to `pygambit`, this tutorial introduces the `gtdraw` package, which can be used to draw extensive form games in Python.\nIf you're running this tutorial on your local machine, you'll need to install the requirements for [gtdraw](https://www.gambit-project.org/gtdraw/), which include LaTeX, in order to run the `gtdraw` cells.\nAnother option for visualising extensive form games is to install the Gambit GUI and use it to load the EFG file generated at the end of this tutorial."
"source": [
"# 2) Extensive-form games\n",
"\n",
"In the first tutorial, we used Gambit to set up the Prisoner's Dilemma, an example of a normal (strategic) form game.\n",
"\n",
"Gambit can also be used to set up extensive-form games; the game is represented as a tree, where each node represents a decision point for a player, and the branches represent the possible actions they can take.\n",
"\n",
"**Example: One-shot trust game with binary actions**\n",
"\n",
"[Kreps (1990)](#references) introduced a game commonly referred to as the **trust game**.\n",
"We will build a one-shot version of this game using Gambit's game transformation operations.\n",
"\n",
"The game can be defined as follows:\n",
"- There are two players, a **Buyer** and a **Seller**.\n",
"- The Buyer moves first and has two actions, **Trust** or **Not trust**.\n",
"- If the Buyer chooses **Not trust**, then the game ends, and both players receive payoffs of `0`.\n",
"- If the Buyer chooses **Trust**, then the Seller has a choice with two actions, **Honor** or **Abuse**.\n",
"- If the Seller chooses **Honor**, both players receive payoffs of `1`;\n",
"- If the Seller chooses **Abuse**, the Buyer receives a payoff of `-1` and the Seller receives a payoff of `2`.\n",
"\n",
"In addition to `pygambit`, this tutorial introduces the `gtdraw` package, which can be used to draw extensive form games in Python.\n",
"If you're running this tutorial on your local machine, you'll need to install the requirements for [gtdraw](https://www.gambit-project.org/gtdraw/), which include LaTeX, in order to run the `gtdraw` cells.\n",
"Another option for visualising extensive form games is to install the Gambit GUI and use it to load the EFG file generated at the end of this tutorial."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5946289b",
"metadata": {},
"outputs": [],
"source": "from gtdraw import draw\n\nimport pygambit as gbt"
"source": [
"from gtdraw import draw\n",
"\n",
"import pygambit as gbt"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -49,7 +76,9 @@
"id": "3cd94917",
"metadata": {},
"outputs": [],
"source": "draw(g)"
"source": [
"draw(g)"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -81,7 +110,9 @@
"id": "45638fda-7e25-4c8e-b709-24b05780581b",
"metadata": {},
"outputs": [],
"source": "draw(g)"
"source": [
"draw(g)"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -111,7 +142,9 @@
"id": "ce41e9fe-cca4-46fb-8e9d-b2c27342e5ef",
"metadata": {},
"outputs": [],
"source": "draw(g)"
"source": [
"draw(g)"
]
},
{
"cell_type": "markdown",
Expand All @@ -134,10 +167,7 @@
"source": [
"g.set_outcome(\n",
" g.root.children[\"Trust\"].children[\"Honor\"],\n",
" outcome=g.add_outcome(\n",
" payoffs=[1, 1],\n",
" label=\"Trustworthy\"\n",
" )\n",
" outcome=g.add_outcome(\"Trustworthy\", [1, 1])\n",
")"
]
},
Expand All @@ -147,7 +177,9 @@
"id": "b3408c55-714e-4a6f-b598-e338839442e4",
"metadata": {},
"outputs": [],
"source": "draw(g)"
"source": [
"draw(g)"
]
},
{
"cell_type": "markdown",
Expand All @@ -166,10 +198,7 @@
"source": [
"g.set_outcome(\n",
" g.root.children[\"Trust\"].children[\"Abuse\"],\n",
" outcome=g.add_outcome(\n",
" payoffs=[-1, 2],\n",
" label=\"Untrustworthy\"\n",
" )\n",
" outcome=g.add_outcome(\"Untrustworthy\", [-1, 2])\n",
")"
]
},
Expand All @@ -179,7 +208,9 @@
"id": "09bedb3a-aac7-46e6-ae93-c47932c746d4",
"metadata": {},
"outputs": [],
"source": "draw(g)"
"source": [
"draw(g)"
]
},
{
"cell_type": "markdown",
Expand All @@ -198,10 +229,7 @@
"source": [
"g.set_outcome(\n",
" g.root.children[\"Not trust\"],\n",
" g.add_outcome(\n",
" payoffs=[0, 0],\n",
" label=\"Opt-out\"\n",
" )\n",
" g.add_outcome(\"Opt-out\", [0, 0])\n",
")"
]
},
Expand All @@ -211,7 +239,9 @@
"id": "cba0e562-2989-4dae-a0f0-b121635ba032",
"metadata": {},
"outputs": [],
"source": "draw(g)"
"source": [
"draw(g)"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -258,7 +288,10 @@
"id": "56899a29-cc53-48db-9eb4-ed2295517400",
"metadata": {},
"outputs": [],
"source": "g = gbt.catalog.load(\"journals/ijgt/selten1975/fig2\")\ndraw(g)"
"source": [
"g = gbt.catalog.load(\"journals/ijgt/selten1975/fig2\")\n",
"draw(g)"
]
},
{
"cell_type": "markdown",
Expand Down
63 changes: 53 additions & 10 deletions doc/tutorials/03_stripped_down_poker.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,50 @@
"cell_type": "markdown",
"id": "98eb65d8",
"metadata": {},
"source": "# 3) Stripped-down poker\n\nIn this tutorial, we'll create an extensive-form representation of a one-card poker game from [Reiley et al (2008)](#references), a classroom game under the name \"stripped-down poker\".\nThis is perhaps the simplest interesting game with imperfect information.\n\nWe'll use \"stripped-down poker\" to demonstrate and explain the following with Gambit:\n\n1. Setting up an extensive-form game with imperfect information using [information sets](#information-sets)\n2. [Computing and interpreting Nash equilibria](#computing-and-interpreting-nash-equilibria) and understanding mixed behaviour and mixed strategy profiles\n3. [Acceptance criteria for Nash equilibria](#acceptance-criteria-for-nash-equilibria)\n\nIn our version of the game, there are two players, **Alice** and **Bob**, and a deck of cards, with equal numbers of **King** and **Queen** cards.\n\n- The game begins with each player putting \\$1 in the pot.\n - A card is dealt at random to Alice.\n - Alice observes her card.\n - Bob does not observe the card.\n- Alice then chooses either to **Bet** or to **Fold**.\n - If she chooses to Fold, Bob wins the pot and the game ends.\n - If she chooses to Bet, she adds another \\$1 to the pot.\n- Bob then chooses either to **Call** or **Fold**.\n - If he chooses to Fold, Alice wins the pot and the game ends.\n - If he chooses to Call, he adds another $1 to the pot.\n- There is then a showdown, in which Alice reveals her card.\n - If she has a King, then she wins the pot.\n - If she has a Queen, then Bob wins the pot.\n\nIn addition to `pygambit`, this tutorial uses the `gtdraw` package, which can be used to draw extensive form games in Python.\nIf you're running this tutorial on your local machine, you'll need to install the requirements for [gtdraw](https://www.gambit-project.org/gtdraw/), which include LaTeX, in order to run the `gtdraw` cells.\nAnother option for visualising extensive form games is to install the Gambit GUI and use it to load a saved EFG file."
"source": [
"# 3) Stripped-down poker\n",
"\n",
"In this tutorial, we'll create an extensive-form representation of a one-card poker game from [Reiley et al (2008)](#references), a classroom game under the name \"stripped-down poker\".\n",
"This is perhaps the simplest interesting game with imperfect information.\n",
"\n",
"We'll use \"stripped-down poker\" to demonstrate and explain the following with Gambit:\n",
"\n",
"1. Setting up an extensive-form game with imperfect information using [information sets](#information-sets)\n",
"2. [Computing and interpreting Nash equilibria](#computing-and-interpreting-nash-equilibria) and understanding mixed behaviour and mixed strategy profiles\n",
"3. [Acceptance criteria for Nash equilibria](#acceptance-criteria-for-nash-equilibria)\n",
"\n",
"In our version of the game, there are two players, **Alice** and **Bob**, and a deck of cards, with equal numbers of **King** and **Queen** cards.\n",
"\n",
"- The game begins with each player putting \\$1 in the pot.\n",
" - A card is dealt at random to Alice.\n",
" - Alice observes her card.\n",
" - Bob does not observe the card.\n",
"- Alice then chooses either to **Bet** or to **Fold**.\n",
" - If she chooses to Fold, Bob wins the pot and the game ends.\n",
" - If she chooses to Bet, she adds another \\$1 to the pot.\n",
"- Bob then chooses either to **Call** or **Fold**.\n",
" - If he chooses to Fold, Alice wins the pot and the game ends.\n",
" - If he chooses to Call, he adds another $1 to the pot.\n",
"- There is then a showdown, in which Alice reveals her card.\n",
" - If she has a King, then she wins the pot.\n",
" - If she has a Queen, then Bob wins the pot.\n",
"\n",
"In addition to `pygambit`, this tutorial uses the `gtdraw` package, which can be used to draw extensive form games in Python.\n",
"If you're running this tutorial on your local machine, you'll need to install the requirements for [gtdraw](https://www.gambit-project.org/gtdraw/), which include LaTeX, in order to run the `gtdraw` cells.\n",
"Another option for visualising extensive form games is to install the Gambit GUI and use it to load a saved EFG file."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "69cbfe81",
"metadata": {},
"outputs": [],
"source": "from gtdraw import draw\n\nimport pygambit as gbt"
"source": [
"from gtdraw import draw\n",
"\n",
"import pygambit as gbt"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -89,7 +124,9 @@
"id": "867cb1d8-7a5d-45d1-9349-9bbc2a4e2344",
"metadata": {},
"outputs": [],
"source": "draw(g, color_scheme=\"gambit\")"
"source": [
"draw(g, color_scheme=\"gambit\")"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -126,7 +163,9 @@
"id": "0c522c2d-992e-48b6-a1f8-0696d33cdbe0",
"metadata": {},
"outputs": [],
"source": "draw(g, color_scheme=\"gambit\")"
"source": [
"draw(g, color_scheme=\"gambit\")"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -166,7 +205,9 @@
"id": "e85b3346-2fea-4a73-aa72-9efb436c68c1",
"metadata": {},
"outputs": [],
"source": "draw(g, color_scheme=\"gambit\")"
"source": [
"draw(g, color_scheme=\"gambit\")"
]
},
{
"cell_type": "markdown",
Expand All @@ -188,10 +229,10 @@
"metadata": {},
"outputs": [],
"source": [
"win_big = g.add_outcome([2, -2], label=\"Win Big\")\n",
"win = g.add_outcome([1, -1], label=\"Win\")\n",
"lose_big = g.add_outcome([-2, 2], label=\"Lose Big\")\n",
"lose = g.add_outcome([-1, 1], label=\"Lose\")"
"win_big = g.add_outcome(\"Win Big\", [2, -2])\n",
"win = g.add_outcome(\"Win\", [1, -1])\n",
"lose_big = g.add_outcome(\"Lose Big\", [-2, 2])\n",
"lose = g.add_outcome(\"Lose\", [-1, 1])"
]
},
{
Expand Down Expand Up @@ -230,7 +271,9 @@
"id": "fdee7b53-7820-44df-9d17-d15d0b9667aa",
"metadata": {},
"outputs": [],
"source": "draw(g, color_scheme=\"gambit\")"
"source": [
"draw(g, color_scheme=\"gambit\")"
]
},
{
"cell_type": "markdown",
Expand Down
26 changes: 19 additions & 7 deletions doc/tutorials/interoperability_tutorials/openspiel.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -468,7 +468,17 @@
"id": "b913fc7a",
"metadata": {},
"outputs": [],
"source": "from gtdraw import draw\n\ndraw(\n gbt_hanabi_game,\n color_scheme=\"gambit\",\n edge_thickness=2,\n action_label_position=0.8,\n shared_terminal_depth=True\n)"
"source": [
"from gtdraw import draw\n",
"\n",
"draw(\n",
" gbt_hanabi_game,\n",
" color_scheme=\"gambit\",\n",
" edge_thickness=2,\n",
" action_label_position=0.8,\n",
" shared_terminal_depth=True\n",
")"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -697,10 +707,10 @@
" actions=[\"Call\", \"Fold\"]\n",
")\n",
"\n",
"win_big = gbt_one_card_poker.add_outcome([2, -2], label=\"Win Big\")\n",
"win = gbt_one_card_poker.add_outcome([1, -1], label=\"Win\")\n",
"lose_big = gbt_one_card_poker.add_outcome([-2, 2], label=\"Lose Big\")\n",
"lose = gbt_one_card_poker.add_outcome([-1, 1], label=\"Lose\")\n",
"win_big = gbt_one_card_poker.add_outcome(\"Win Big\", [2, -2])\n",
"win = gbt_one_card_poker.add_outcome(\"Win\", [1, -1])\n",
"lose_big = gbt_one_card_poker.add_outcome(\"Lose Big\", [-2, 2])\n",
"lose = gbt_one_card_poker.add_outcome(\"Lose\", [-1, 1])\n",
"\n",
"# Alice folds, Bob wins small\n",
"gbt_one_card_poker.set_outcome(\n",
Expand Down Expand Up @@ -741,7 +751,9 @@
"id": "ed920d33-b7c6-4cc1-b055-7244a5bf42d8",
"metadata": {},
"outputs": [],
"source": "draw(gbt_one_card_poker, color_scheme=\"gambit\")"
"source": [
"draw(gbt_one_card_poker, color_scheme=\"gambit\")"
]
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -833,7 +845,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.13"
"version": "3.13.5"
}
},
"nbformat": 4,
Expand Down
Loading
Loading