polymatrix_game

” Tools for working with games in Polymatrix form.

In a Polymatrix Game, the payoff to a player is the sum of their payoffs from bimatrix games against each player. i.e. If two opponents deviate, the change in payoff is the sum of the changes in payoff of each deviation.

Examples

Turn a Matching Pennies Normal Form Game into a Polymatrix Game.

>>> matching_pennies_bimatrix = [
...     [(1, -1), (-1, 1)], [(-1, 1), (1, -1)]]
>>> nfg = NormalFormGame(matching_pennies_bimatrix)
>>> polymg = PolymatrixGame.from_nf(nfg)
>>> print(polymg)
2-player PolymatrixGame with payoff matrices:
(0, 1):
[[ 1. -1.]
 [-1.  1.]]

(1, 0):
[[-1.  1.]
 [ 1. -1.]]

(An example of a multiplayer game is not given because then the polymatrix representation would not be unique and therefore could not be reliably quoted for this doctest.)

class quantecon.game_theory.polymatrix_game.PolymatrixGame(polymatrix: Mapping[tuple[int, int], Sequence[Sequence[float]]], nums_actions: Iterable[int] | None = None)

Bases: object

Polymatrix Game.

polymatrix[(a, b)] is a 2D matrix, the payoff matrix of a in the bimatrix game between a and b; player number a is the row player and player number b is the column player.

Attributes:

Nscalar(int)

Number of players.

nums_actionstuple(int)

The number of actions available to each player.

polymatrixdict[tuple(int), ndarray(float, ndim=2)]

Maps each pair of player numbers to a matrix.

Methods

from_nf(nf[, is_polymatrix])	Creates a Polymatrix from a Normal Form Game.
get_player(player_idx)	Calculates the payoff function of a player.
range_of_payoffs()	The lowest and highest components of payoff from head to head games.
to_nfg()	Creates a Normal Form Game from the Polymatrix Game.

classmethod from_nf(nf: NormalFormGame, is_polymatrix: bool = True)

Creates a Polymatrix from a Normal Form Game.

Precise if possible; many Normal Form Games are not representable precisely with a Polymatrix. With payoffs (not costs).

Parameters:

nfNormalFormGame

Normal Form Game to convert.

is_polymatrixbool, optional

Is the Normal Form Game precisely convertible to a Polymatrix Game. By default True

Returns:

Self

The Polymatrix Game.

get_player(player_idx: int) → Player

Calculates the payoff function of a player.

Parameters:

player_idxint

Player number who we want to extract.

Returns:

Player

Player object which has the player’s payoff function.

range_of_payoffs() → tuple[float, float]

The lowest and highest components of payoff from head to head games.

Returns:

tuple[float, float]

Tuple of minimum and maximum.

to_nfg() → NormalFormGame

Creates a Normal Form Game from the Polymatrix Game.

Returns:

NormalFormGame

The game in Normal Form.

quantecon.game_theory.polymatrix_game.hh_payoff_player(nfg: NormalFormGame, my_player_number: int, my_action_number: int, is_polymatrix: bool = True) → dict[tuple[int, int], float]

Head-to-head payoff components.

hh stands for head-to-head. Calculates the payoffs to a player when they play an action with values at the actions of other players that try to sum to the payoff. Precise when the game can be represented with a polymatrix; otherwise, an approximation using least squares on the payoffs at every action combination. If an approximation, it may drastically change the game, use with caution.

Parameters:

nfgNormalFormGame

The game.

my_player_numberint

The number of the player making the action.

my_action_numberint

The number of our player’s action.

is_polymatrixbool, optional

Is the game represented by this normal form actually a polymatrix game. Defaults to True.

Returns:

dict[tuple[int, int], float]

Dictionary giving a (approximate) component of the payoff at each other player and their action.