game_converters

Utilities for converting between representations of games.

Currently supports reading and writing the GameTracer .gam text format [1].

Examples

Create a QuantEcon NormalFormGame from a .gam file storing a 3-player Minimum Effort Game:

>>> import os
>>> import quantecon.game_theory as gt
>>> filepath = os.path.dirname(gt.__file__)
>>> filepath = os.path.join(filepath, 'tests', 'game_files',
...                         'minimum_effort_game.gam')
>>> nfg = gt.from_gam(filepath)
>>> print(nfg)
3-player NormalFormGame with payoff profile array:
[[[[  1.,   1.,   1.],   [  1.,   1.,  -9.],   [  1.,   1., -19.]],
  [[  1.,  -9.,   1.],   [  1.,  -9.,  -9.],   [  1.,  -9., -19.]],
  [[  1., -19.,   1.],   [  1., -19.,  -9.],   [  1., -19., -19.]]],

 [[[ -9.,   1.,   1.],   [ -9.,   1.,  -9.],   [ -9.,   1., -19.]],
  [[ -9.,  -9.,   1.],   [  2.,   2.,   2.],   [  2.,   2.,  -8.]],
  [[ -9., -19.,   1.],   [  2.,  -8.,   2.],   [  2.,  -8.,  -8.]]],

 [[[-19.,   1.,   1.],   [-19.,   1.,  -9.],   [-19.,   1., -19.]],
  [[-19.,  -9.,   1.],   [ -8.,   2.,   2.],   [ -8.,   2.,  -8.]],
  [[-19., -19.,   1.],   [ -8.,  -8.,   2.],   [  3.,   3.,   3.]]]]

References

[1]

Ben Blum, Daphne Koller, Christian Shelton, “Game Theory: GameTracer,” http://dags.stanford.edu/Games/gametracer.html

class quantecon.game_theory.game_converters.GAMPayoffVector(nums_actions, payoffs)

Bases: object

Internal intermediate representation that stores payoffs in a single flat 1-dim array.

Payoff values are ordered as in the GameTracer .gam format: 1. Player-major blocks: player 0, …, player N-1. 2. Within each block, action profiles are ordered with player 0

varying fastest, then player 1, …, player N-1 (i.e., Fortran/column-major order).

Attributes:

Nscalar(int)

Number of players.

nums_actionstuple(int)

Tuple of the numbers of actions, one for each player.

payoffsndarray(ndim=1)

Array storing payoffs in .gam order.

Methods

from_nfg(g[, dtype])	Construct a GAMPayoffVector from a NormalFormGame g.
to_nfg([dtype])	Construct a NormalFormGame from self.

classmethod from_nfg(g, dtype=None)

Construct a GAMPayoffVector from a NormalFormGame g.

Examples

>>> player0 = Player([[0, 3], [1, 4], [2, 5]])
>>> player1 = Player([[6, 7, 8], [9, 10, 11]])
>>> g = NormalFormGame((player0, player1))
>>> print(g)
2-player NormalFormGame with payoff profile array:
[[[ 0,  6],  [ 3,  9]],
 [[ 1,  7],  [ 4, 10]],
 [[ 2,  8],  [ 5, 11]]]
>>> p = GAMPayoffVector.from_nfg(g)
>>> p.payoffs
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11])

to_nfg(dtype=None)

Construct a NormalFormGame from self.

Examples

>>> nums_actions = (3, 2)
>>> payoffs = np.arange(12)
>>> p = GAMPayoffVector(nums_actions, payoffs)
>>> g = p.to_nfg()
>>> print(g)
2-player NormalFormGame with payoff profile array:
[[[ 0,  6],  [ 3,  9]],
 [[ 1,  7],  [ 4, 10]],
 [[ 2,  8],  [ 5, 11]]]

class quantecon.game_theory.game_converters.GAMReader

Bases: object

Parser for the GameTracer .gam format.

Methods

from_file(file_path)	Read from a .gam format file.
from_string(string)	Read from a .gam format string.
from_url(url)	Read from a URL.

classmethod from_file(file_path)

Read from a .gam format file.

classmethod from_string(string)

Read from a .gam format string.

classmethod from_url(url)

Read from a URL.

class quantecon.game_theory.game_converters.GAMWriter

Bases: object

Serializer for the GameTracer .gam format.

Methods

to_file(g, file_path)	Write g to a file in GameTracer .gam format.
to_string(g)	Return the GameTracer .gam string representation of g.

classmethod to_file(g, file_path)

Write g to a file in GameTracer .gam format.

classmethod to_string(g)

Return the GameTracer .gam string representation of g.

quantecon.game_theory.game_converters.from_gam(filename: str) → NormalFormGame

Read a GameTracer .gam file and return a NormalFormGame.

Parameters:

filenamestr

Path to .gam file.

Returns:

NormalFormGame

The game described by the .gam file.

Examples

Save a .gam format string in a temporary file:

>>> import tempfile
>>> fname = tempfile.mkstemp()[1]
>>> with open(fname, mode='w') as f:
...       _ = f.write("""\
... 2
... 3 2
...
... 3 2 0 3 5 6 3 2 3 2 6 1""")

Read the file:

>>> g = from_gam(fname)
>>> print(g)
2-player NormalFormGame with payoff profile array:
[[[3, 3],  [3, 2]],
 [[2, 2],  [5, 6]],
 [[0, 3],  [6, 1]]]

quantecon.game_theory.game_converters.from_gam_string(string)

Read a .gam format string and return a NormalFormGame.

Parameters:

stringstr

String in .gam format.

Returns:

NormalFormGame

The game described by the .gam string.

Examples

>>> string = """\
... 2
... 3 2
...
... 3 2 0 3 5 6 3 2 3 2 6 1"""
>>> g = from_gam_string(string)
>>> print(g)
2-player NormalFormGame with payoff profile array:
[[[3, 3],  [3, 2]],
 [[2, 2],  [5, 6]],
 [[0, 3],  [6, 1]]]

quantecon.game_theory.game_converters.from_gam_url(url)

Read a GameTracer .gam file from a URL and return a NormalFormGame.

Parameters:

urlstr

String containing a URL of the .gam file.

Returns:

NormalFormGame

The game described by the .gam file.

quantecon.game_theory.game_converters.to_gam(g, file_path=None)

Write a NormalFormGame to a file in .gam format.

Parameters:

gNormalFormGame

file_pathstr, optional(default=None)

Path to the file to write to. If None, the result is returned as a string.

Returns:

None or str