Games

Game theory utilities.

class freeride.games.Game(payoffs1, payoffs2, *, player_names: Sequence[str] | None = None, action_names: Sequence[Sequence[str]] = (('action 0', 'action 1'), ('action 0', 'action 1')))

Bases: object

Simple two-player game.

Parameters:

• payoffs1 (array-like) – Payoff matrix for player 1. Rows correspond to player 1 actions and columns correspond to player 2 actions.

• payoffs2 (array-like) – Payoff matrix for player 2 with the same shape as payoffs1.

• player_names (sequence of str, optional) – Names for the row and column players. If omitted the row player name is randomly chosen from {"Anna", "Alice"} and the column player name from {"Boris", "Bob"}.

__init__(payoffs1, payoffs2, *, player_names: Sequence[str] | None = None, action_names: Sequence[Sequence[str]] = (('action 0', 'action 1'), ('action 0', 'action 1')))

property shape: Tuple[int, int]

best_response(profile: Tuple[int, int]) → List[int]

Return a best response profile to profile.

Parameters:

profile (tuple of int) – Current actions (i, j) for players A and B.

best_responses() → Tuple[List[List[int]], List[List[int]]]

Return best responses for each pure strategy profile.

nash_equilibria() → List[Tuple[str, str]]

Compute pure strategy Nash equilibria.

Returns:

List of Nash equilibria as strategy profiles (action name pairs). Each equilibrium is a tuple of (player1_action, player2_action). A Nash equilibrium is a strategy profile where no player can unilaterally deviate and improve their payoff.

Return type:

list of tuple of str

nash() → List[Tuple[str, str]]

Alias for nash_equilibria().

mixed_strategy_equilibrium() → Tuple[float, float]

Return mixed strategy equilibrium for 2x2 games.

weakly_dominant_strategies() → dict

Return weakly dominant strategies for both players.

table(ax: matplotlib.pyplot.Axes | None = None, show_solution: bool = True, player_names: Sequence[str] | None = None, action_names: Sequence[Sequence[str]] | None = None, usetex: bool = False) → matplotlib.pyplot.Axes

Plot a payoff table.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axis on which to draw. If None, uses matplotlib.pyplot.gca().

• show_solution (bool, default True) – Highlight best responses and Nash equilibria when True.

• player_names (sequence of str, optional) – Names for the row and column players. Defaults to the names stored on the Game instance.

• action_names (sequence of sequence of str, optional) – action_names[0] are actions for player A and action_names[1] for player B. Defaults to the names stored on the Game instance.

• usetex (bool, default False) – Use LaTeX for text rendering and underline best responses when True. When False, best responses are highlighted with colored boxes.

Returns:

The axis containing the table.

Return type:

matplotlib.axes.Axes

Notes

Supports arbitrary rows       imes cols games.

plot_payoff_hull(ax: matplotlib.pyplot.Axes | None = None, annotate: bool = False) → matplotlib.pyplot.Axes

Plot the convex hull of payoff pairs for the game.

classmethod prisoners_dilemma() → Game

Return the classic Prisoner’s Dilemma game.

classmethod matching_pennies() → Game

Return the Matching Pennies game.

classmethod stag_hunt() → Game

Return the Stag Hunt coordination game.

classmethod battle_of_the_sexes() → Game

Return the Battle of the Sexes coordination game.

classmethod bach_or_stravinsky() → Game

Return the Bach or Stravinsky coordination game.

classmethod pure_coordination() → Game

Return a simple pure coordination game.

classmethod chicken() → Game

Return the classic Chicken (Hawk-Dove) game.

classmethod rock_paper_scissors() → Game

Return the Rock-Paper-Scissors game.

freeride.games.NormalFormGame

alias of Game

The Game constructor randomly assigns the row player the name Anna or Alice and the column player Boris or Bob when no names are supplied. The built-in constructors such as prisoners_dilemma and matching_pennies also label the available actions so that tables and other output are more informative out of the box.

Highlighting Options

Game.table accepts a usetex argument. When set to True the underlying text is rendered with LaTeX and best responses are underlined. When False (the default), best responses are indicated with colored boxes around the payoff of the player with the best response and no raw \underline appears in the output.

Example:

import matplotlib.pyplot as plt
from freeride.games import Game

p1 = [[3, 0], [5, 1]]
p2 = [[3, 5], [0, 1]]
g = Game(p1, p2)
ax = g.table(usetex=False)
plt.close(ax.figure)

Battle of the Sexes Example

Game comes with constructors for common games. The battle_of_the_sexes method returns the classic coordination game with players Anna and Boris and actions Opera and Boxing Match already labeled. The table below was created with usetex=False so that best responses are highlighted with colored boxes on the payoff entries themselves.

In this version, Boris prefers the boxing match while Anna prefers the opera.

from freeride.games import Game

ax = Game.battle_of_the_sexes().table()
ax.figure.savefig("battle_of_the_sexes.svg", transparent=True)
plt.close(ax.figure)

Prisoner’s Dilemma Example

The prisoner’s dilemma captures the tension between individual and collective interest. Mutual cooperation is Pareto efficient but each player has an incentive to defect.

from freeride.games import Game

ax = Game.prisoners_dilemma().table()
ax.figure.savefig("prisoners_dilemma.svg", transparent=True)
plt.close(ax.figure)

Matching Pennies Example

Matching pennies is a zero‑sum game with no pure strategy equilibrium. Each player wants to match or mismatch the other’s choice.

from freeride.games import Game

ax = Game.matching_pennies().table()
ax.figure.savefig("matching_pennies.svg", transparent=True)
plt.close(ax.figure)

Stag Hunt Example

The stag hunt models coordination with a safe action (hunting hare) and a potentially higher payoff from mutual cooperation (hunting stag).

from freeride.games import Game

ax = Game.stag_hunt().table()
ax.figure.savefig("stag_hunt.svg", transparent=True)
plt.close(ax.figure)

Pure Coordination Example

This simple coordination game rewards players for choosing the same action.

from freeride.games import Game

ax = Game.pure_coordination().table()
ax.figure.savefig("pure_coordination.svg", transparent=True)
plt.close(ax.figure)

Chicken Example

The game of chicken (or hawk–dove) illustrates the conflict between standing firm and yielding.

from freeride.games import Game

ax = Game.chicken().table()
ax.figure.savefig("chicken.svg", transparent=True)
plt.close(ax.figure)