games package¶

Submodules¶

games.bar_crowding module¶

A 3-player bar-crowding game’s version of El Farol Bar problem (https://en.wikipedia.org/wiki/El_Farol_Bar_problem).

Reference:: [Matthew Rouso’s lecture](https://www.youtube.com/watch?v=P7Dg5FRH0cc)

class games.bar_crowding.BAR_CROWDING_ACTIONS(value)[source]¶

Bases: imperfecto.misc.utils.lessVerboseEnum, enum.IntEnum

Available actions for the bar-crowding game.

GO_TO_BAR = 0¶

STAY_HOME = 1¶

class games.bar_crowding.BarCrowdingGame(players)[source]¶

Bases: imperfecto.games.game.NormalFormGame

A 3-player bar-crowding game’s version of El Farol Bar problem (https://en.wikipedia.org/wiki/El_Farol_Bar_problem).

Each player has two actions: go to the bar and stay at home. Each player wants to go to the bar but if all three of them go to the bar, the bar will be crowded. If only one player go to the bar, then they will feel lonely and silly. Ideally, exactly two players should go to the bar and have fun.

Payoff:

If the bar is overcrowded, every player get a payoff of -1.

If a player shows up and feel silly, they get a payoff of 0.

If a player stays at home, they get a payoff of +1.

If exactly two players go to the bar, they get a payoff of +2.

Nash Equilibrium:

The pure Nash equilibria are

All three stay at home. (payoff = 1 for all)

2. Three outcomes where exactly two players go to the bar, and one player stays at home. (payoff = 1 for one player, 2 for the other two)

actions¶: alias of games.bar_crowding.BAR_CROWDING_ACTIONS

n_players: int = 3¶

get_payoffs(history)[source]¶

Return the payoff for each player at the current node.

Note

history must be a terminal node.

Parameters: history (Sequence[BAR_CROWDING_ACTIONS]) – The history of the game.
Return type: Sequence[float]
Returns: The payoffs of the players at the end of the game.

games.game module¶

A collection of base game classes.

Classes:

ExtensiveFormGame
NormalFormGame

class games.game.ExtensiveFormGame(players)[source]¶

Bases: abc.ABC

Abstract class for extensive form games.

In an extensive form game, players have some private information, and are unsure about the true state of the world.

Note

ExtensiveFormGame subclass must have class-level attribute actions, and n_players.

Parameters: players (Sequence[Player]) – The players of the game.

actions¶

The actions of the game (class-level attribute).

Type: enum.EnumMeta

n_players¶

The number of players in the game (class-level attribute).

Type: int

players¶

The players of the game.

Type: Sequence[Player]

n_players: int¶

actions: enum.EnumMeta¶

property players: Sequence[imperfecto.algos.player.Player]¶

The players of the game.

Return type: Sequence[Player]

abstract get_active_player(history)[source]¶

Get the active player of the game at the current decision point.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: Player
Returns: The active player of the game at the current decision point.

abstract is_terminal(history)[source]¶

Check if the game is in a terminal state.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: bool
Returns: True if the game is in a terminal state, False otherwise.

abstract get_payoffs(history)[source]¶

Return the payoff for each player at the current node.

Note

history must be a terminal node.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: Sequence[float]
Returns: The payoffs of the players at the end of the game.

abstract get_infostate(history)[source]¶

Return the infostate (i.e. the information set) of the game.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: str
Returns: A string representation of the infostate of the game.

history_to_str(history)[source]¶

Return a string representation of the history of the game.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: str
Returns: A string representation of the history of the game.

play()[source]¶

Play the game with the current players and their strategies and return the payoffs.

Return type: Tuple[Sequence[IntEnum], Sequence[float]]
Returns: A tuple of the play-out history of the game and the payoffs of the players.

static shorten_history(history_str)[source]¶

Shorten history string. Games with long action names should override this method.

Parameters: history_str (str) – history string to shorten.
Return type: str
Returns: a shortened history string.

class games.game.NormalFormGame(players)[source]¶

Bases: games.game.ExtensiveFormGame, abc.ABC

N-player normal form game.

This class of game is a special form of extensive-form games. A normal form game involves every player making simultaneous moves. Thus, they are unsure about each other’s move.

Parameters: players (Sequence[Player]) – The players of the game.

is_terminal(history)[source]¶

Check if the game is in a terminal state.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: bool
Returns: True if the game is in a terminal state, False otherwise.

get_infostate(history)[source]¶

Return the infostate (i.e. the information set) of the game.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: str
Returns: A string representation of the infostate of the game.

get_active_player(history)[source]¶

Get the active player of the game at the current decision point.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: Player
Returns: The active player of the game at the current decision point.

games.kuhn_poker module¶

An implement of Kuhn Poker game.

We have two players. We have three cards: Jack, Queen, King, where King beats Queen and Queen beats Jack. In this game, each player gets a random card. On a turn, a player can either

pass: do nothing. The opponent wins all chip in the pot.
bet: place a chip in the pot.

After two passes or two bets (not necessarily consecutive), the game ends. Player with the highest card wins.

The Maximum depth of the game tree is 3. The game tree is as follows. Game tree:

      [chance]
         |
    assign cards
         |
      [player1]
      /      \

  [pass]      [bet]
   |             |
[player2]       [player2]
  /   \         /   \
pass    bet   pass     bet
 |      |       |         |
 (h)  [player1]   (1)       (h)
      /   \

    pass   bet
      |     |
      (2)   (h)

Leaf nodes notation:

(h): player has highest card wins!
(1): player 1 wins! (player 2 chickens out)
(2): player 2 wins! (player 1 chickens out)

In this game, we have 12 info-sets. Each info-set has 2 states since the opponent can have any of the two cards that I’m not already holding. We have 4 decision nodes (excluding the chance’s action), and a player’s private information consists of their own card, which takes 3 possible values so we have 3 * 4 = 12 info sets.

Note

There’s a subtle difference between the number of info sets and the number of nodes per info set (the size of the info set). The size of the info set tells us how many worlds are consistent with the player’s observations so far. The number of info sets is more “meta”. A player, without entering into a game / trajectory, can reason ahead about the different info sets that they can be in once some partial observations are available to them when the game starts.

class games.kuhn_poker.KUHN_POKER_ACTIONS(value)[source]¶

Bases: imperfecto.misc.utils.lessVerboseEnum, enum.IntEnum

Available actions in Kuhn Poker.

PASS = 0¶

BET = 1¶

class games.kuhn_poker.KUHN_POKER_CHANCE_ACTIONS(value)[source]¶

Bases: imperfecto.misc.utils.lessVerboseEnum, enum.IntEnum

Availble chance actions in Kuhn Poker.

We have 3 cards J, Q, K dealt randomly to 2 players.

JQ = 0¶

JK = 1¶

QK = 2¶

QJ = 3¶

KJ = 4¶

KQ = 5¶

class games.kuhn_poker.KuhnPokerGame(players)[source]¶

Bases: imperfecto.games.game.ExtensiveFormGame

A Kuhn Poker (https://en.wikipedia.org/wiki/Kuhn_poker) game class.

Payoff:: The winner wins whatever is in the pot. A player can win either in showdown by having the highest card or win by having their opponent chickens out.
Nash equilibrium:: There are infinitely many Nash equilibria. Player one can choose any probability alpha in [0, 1/3] to bet when having Jack, and pass when the other play bets. They should bet with probability 3 * alpha when having a King, and if the other player bets, they should bet. They should always pass when having a Queen, and if the other player bets, they should pass. The second player should always bet when having a King; when having a Queen, check if possible otherwise call with probability 1/3. When they have a Jack, they should never call and bet with probability 1/3. The first player’s expected payoff under Nash equilibria is -1/18.

actions¶: alias of games.kuhn_poker.KUHN_POKER_ACTIONS

chance_actions¶: alias of games.kuhn_poker.KUHN_POKER_CHANCE_ACTIONS

n_players: int = 2¶

has_chance_player = True¶

is_terminal(history)[source]¶

Check if the game is in a terminal state.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Returns: True if the game is in a terminal state, False otherwise.

get_active_player(history)[source]¶

Get the active player of the game at the current decision point.

Parameters: history (Sequence[IntEnum]) – The history of the game.
Return type: Player
Returns: The active player of the game at the current decision point.

get_winner(chance_action)[source]¶

Return the winner of the game given a chance action.

Parameters: chance_action (KUHN_POKER_CHANCE_ACTIONS) – the chance action
Return type: int
Returns: the winner (player_id) of the game

showdown(history)[source]¶

Return the payoff value of the game in the showdown case given a history.

Winner is the player with the highest card. We don’t take into account the amount of chips in the pot. Winner gets +1 point while loser gets -1 point.

Parameters: history – the history of the game
Return type: ndarray
Returns: the payoff value of the game in the showdown case

get_payoffs(history)[source]¶

Return the payoff for each player at the current node.

Note

history must be a terminal node.

Parameters: history – The history of the game.
Returns: The payoffs of the players at the end of the game.

get_card(chance_action, player_id)[source]¶

Return the card that a chance action has dealt to a player.

Parameters

chance_action (KUHN_POKER_CHANCE_ACTIONS) – a chance action
player_id (int) – the player who receives the card

Return type

str

Returns

the card that the chance action has dealt to the player

get_infostate(history)[source]¶

Return the infostate (i.e. the information set) of the game.

Parameters: history (Sequence[Enum]) – The history of the game.
Return type: str
Returns: A string representation of the infostate of the game.

chance_action()[source]¶

Return a chance action.

We have 3 cards J, Q, K dealt randomly to 2 players. This function handles the card dealing.

Return type: KUHN_POKER_CHANCE_ACTIONS
Returns: a chance action

static shorten_history(history_str)[source]¶

Shorten history string. For example, “KJ-PASS-BET” -> “KJPB”. :type history_str: str :param history_str: history string

Return type: str
Returns: A shortened history string

games.prisoner_dilemma module¶

A 2-player vintage Prisoner’s Dilemma game (https://en.wikipedia.org/wiki/Prisoner%27s_dilemma).

This is a classic paradox in game theory where a stable outcome (i.e., a Nash equilibrium) is worse off for both players.

class games.prisoner_dilemma.PRISONER_DILEMMA_ACTIONS(value)[source]¶

Bases: imperfecto.misc.utils.lessVerboseEnum, enum.IntEnum

Available actions in the Prisoner’s Dilemma game.

SNITCH = 0¶

SILENCE = 1¶

class games.prisoner_dilemma.PrisonerDilemmaGame(players)[source]¶

Bases: imperfecto.games.game.NormalFormGame

A 2-player vintage classical Prisoner’s Dilemma game. (https://en.wikipedia.org/wiki/Prisoner%27s_dilemma)

Two players are crime partners in a robbery. They were arrested by the police but the police has no evidence to convict them. So the police commisioner sits each player on a separate room and offers them a deal. If one player confesses and snitches against the other, the confessor will go free and their partner will receive 3 years. If both players stay silent, they will serve 1 year for another mirror crime that the police was able to catch. However, if both of them betray each other, they will both serve 2 years.

Payoff:

If both silence, get 1 year each.
If both betray, get 2 years each.
If one silence and one snitches, the snitch goes free and the silent partner gets 3 years.

Nash Equilibria:

The only Nash Equilibrium is when both players snitch. (payoff = -2 for both)

actions¶: alias of games.prisoner_dilemma.PRISONER_DILEMMA_ACTIONS

n_players: int = 2¶

get_payoffs(history)[source]¶

Return the payoff for each player at the current node.

Note

history must be a terminal node.

Parameters: history (Sequence[PRISONER_DILEMMA_ACTIONS]) – The history of the game.
Return type: Sequence[float]
Returns: The payoffs of the players at the end of the game.

games.rock_paper_scissor module¶

A collection of 2-player rock paper scissor games.

This includes:

A Standard Rock Paper Scissor class.
An Asymmetric Rock Paper Scissor class.

class games.rock_paper_scissor.ROCK_PAPER_SCISSOR_ACTIONS(value)[source]¶

Bases: imperfecto.misc.utils.lessVerboseEnum, enum.IntEnum

Available actions for the rock-paper-scissors game.

ROCK = 0¶

PAPER = 1¶

SCISSOR = 2¶

class games.rock_paper_scissor.RockPaperScissorGame(players)[source]¶

Bases: imperfecto.games.game.NormalFormGame

A (standard) 2-player rock-paper-scissor (extensive-form) game.

Payoff:: Rock beats scissors, scissors beats paper, and paper beats rock. Winner gets +1 payoff, loser gets -1 payoff.
Nash Equilibrium:: The nash strategy (unexploitable) is (1/3, 1/3, 1/3) (payoff = 0 for all)

actions¶: alias of games.rock_paper_scissor.ROCK_PAPER_SCISSOR_ACTIONS

n_players: int = 2¶

get_payoffs(history)[source]¶

Return the payoff for each player at the current node.

Note

history must be a terminal node.

Parameters: history (Sequence[ROCK_PAPER_SCISSOR_ACTIONS]) – The history of the game.
Return type: Sequence[float]
Returns: The payoffs of the players at the end of the game.

class games.rock_paper_scissor.AsymmetricRockPaperScissorGame(players)[source]¶

Bases: games.rock_paper_scissor.RockPaperScissorGame

An asymmetric 2-player rock-paper-scissors (extensive-form) game.

Payoff:: Rock beats scissors, scissors beats paper, and paper beats rock. But winner gets +2 payoff, loser gets -2 payoff when someone plays scissor. Otherwise, winner gets +1 payoff, loser gets -1 payoff.
Nash Equilibrium:: The Nash strategy (unexploitable) is (0.4, 0.4, 0.2) (payoff = 0 for all)

get_payoffs(history)[source]¶

Override the get_payoffs function of standard rock-paper-scissors.

The winner gets +2 payoff, loser gets -2 payoff when someone plays scissor. Otherwise, winner gets +1 payoff, loser gets -1 payoff.

Parameters: history (Sequence[ROCK_PAPER_SCISSOR_ACTIONS]) – The history of the game.
Return type: Sequence[float]
Returns: The payoffs of the players.

games package¶

Submodules¶

games.bar_crowding module¶

games.game module¶

games.kuhn_poker module¶

games.prisoner_dilemma module¶

games.rock_paper_scissor module¶

Module contents¶