Python interface to Gambit library

Gambit provides a Python interface for programmatic manipulation of games. This section documents this interface, which is under active development. Refer to the instructions for building the Python interface to compile and install the Python extension.

A tutorial introduction

Building an extensive game

The function Game.new_tree() creates a new, trivial extensive game, with no players, and only a root node:

In [1]: import gambit

In [2]: g = gambit.Game.new_tree()

In [3]: len(g.players)
Out[3]: 0

The game also has no title. The title attribute provides access to a game’s title:

In [4]: str(g)
Out[4]: "<Game ''>"

In [5]: g.title = "A simple poker example"

In [6]: g.title
Out[6]: 'A simple poker example'

In [7]: str(g)
Out[7]: "<Game 'A simple poker example'>"

The players attribute of a game is a collection of the players. As seen above, calling len() on the set of players gives the number of players in the game. Adding a Player to the game is done with the add() member of players:

In [8]: p = g.players.add("Alice")

In [9]: p
Out[9]: <Player [0] 'Alice' in game 'A simple poker example'>

Each Player has a text string stored in the label attribute, which is useful for human identification of players:

In [10]: p.label
Out[10]: 'Alice'

Game.players can be accessed like a Python list:

In [11]: len(g.players)
Out[11]: 1

In [12]: g.players[0]
Out[12]: <Player [0] 'Alice' in game 'A simple poker example'>

In [13]: g.players
Out[13]: [<Player [0] 'Alice' in game 'A simple poker example'>]

Building a strategic game

Games in strategic form are created using Game.new_table(), which takes a list of integers specifying the number of strategies for each player:

In [1]: g = gambit.Game.new_table([2,2])

In [2]: g.title = "A prisoner's dilemma game"

In [3]: g.players[0].label = "Alphonse"

In [4]: g.players[1].label = "Gaston"

In [5]: g
Out[5]:
NFG 1 R "A prisoner's dilemma game" { "Alphonse" "Gaston" }

{ { "1" "2" }
{ "1" "2" }
}
""

{
}
0 0 0 0

The strategies collection for a Player lists all the strategies available for that player:

In [6]: g.players[0].strategies
Out[6]: [<Strategy [0] '1' for player 'Alphonse' in game 'A
prisoner's dilemma game'>,
         <Strategy [1] '2' for player 'Alphonse' in game 'A prisoner's dilemma game'>]

In [7]: len(g.players[0].strategies)
Out[7]: 2

In [8]: g.players[0].strategies[0].label = "Cooperate"

In [9]: g.players[0].strategies[1].label = "Defect"

In [10]: g.players[0].strategies
Out[10]: [<Strategy [0] 'Cooperate' for player 'Alphonse' in game 'A
prisoner's dilemma game'>,
          <Strategy [1] 'Defect' for player 'Alphonse' in game 'A prisoner's dilemma game'>]

The outcome associated with a particular combination of strategies is accessed by treating the game like an array. For a game g, g[i,j] is the outcome where the first player plays his i th strategy, and the second player plays his j th strategy. Payoffs associated with an outcome are set or obtained by indexing the outcome by the player number. For a prisoner’s dilemma game where the cooperative payoff is 8, the betrayal payoff is 10, the sucker payoff is 2, and the noncooperative (equilibrium) payoff is 5:

In [11]: g[0,0][0] = 8

In [12]: g[0,0][1] = 8

In [13]: g[0,1][0] = 2

In [14]: g[0,1][1] = 10

In [15]: g[1,0][0] = 10

In [16]: g[1,1][1] = 2

In [17]: g[1,0][1] = 2

In [18]: g[1,1][0] = 5

In [19]: g[1,1][1] = 5

Alternatively, one can use Game.from_arrays() in conjunction with numpy arrays to construct a game with desired payoff matrices more directly, as in:

In [20]: m = numpy.array([ [ 8, 2 ], [ 10, 5 ] ], dtype=gambit.Rational)

In [21]: g = gambit.Game.from_arrays(m, numpy.transpose(m))

Reading a game from a file

Games stored in existing Gambit savefiles in either the .efg or .nfg formats can be loaded using Game.read_game():

In [1]: g = gambit.Game.read_game("e02.nfg")

In [2]: g
Out[2]:
NFG 1 R "Selten (IJGT, 75), Figure 2, normal form" { "Player 1" "Player 2" }

{ { "1" "2" "3" }
{ "1" "2" }
}
""

{
{ "" 1, 1 }
{ "" 0, 2 }
{ "" 0, 2 }
{ "" 1, 1 }
{ "" 0, 3 }
{ "" 2, 0 }
}
1 2 3 4 5 6

Iterating the pure strategy profiles in a game

Each entry in a strategic game corresponds to the outcome arising from a particular combination fo pure strategies played by the players. The property Game.contingencies is the collection of all such combinations. Iterating over the contingencies collection visits each pure strategy profile possible in the game:

In [1]: g = gambit.Game.read_game("e02.nfg")

In [2]: list(g.contingencies)
Out[2]: [[0, 0], [0, 1], [1, 0], [1, 1], [2, 0], [2, 1]]

Each pure strategy profile can then be used to access individual outcomes and payoffs in the game:

In [3]: for profile in g.contingencies:
   ...:     print profile, g[profile][0], g[profile][1]
   ...:
[0, 0] 1 1
[0, 1] 1 1
[1, 0] 0 2
[1, 1] 0 3
[2, 0] 0 2
[2, 1] 2 0

Mixed strategy and behavior profiles

A MixedStrategyProfile object, which represents a probability distribution over the pure strategies of each player, is constructed using Game.mixed_strategy_profile(). Mixed strategy profiles are initialized to uniform randomization over all strategies for all players.

Mixed strategy profiles can be indexed in three ways.

  1. Specifying a strategy returns the probability of that strategy being played in the profile.
  2. Specifying a player returns a list of probabilities, one for each strategy available to the player.
  3. Profiles can be treated as a list indexed from 0 up to the number of total strategies in the game minus one.

This sample illustrates the three methods:

In [1]: g = gambit.Game.read_game("e02.nfg")

In [2]: p = g.mixed_strategy_profile()

In [3]: list(p)
Out[3]: [0.33333333333333331, 0.33333333333333331, 0.33333333333333331, 0.5, 0.5]

In [4]: p[g.players[0]]
Out[4]: [0.33333333333333331, 0.33333333333333331, 0.33333333333333331]

In [5]: p[g.players[1].strategies[0]]
Out[5]: 0.5

The expected payoff to a player is obtained using MixedStrategyProfile.payoff():

In [6]: p.payoff(g.players[0])
Out[6]: 0.66666666666666663

The standalone expected payoff to playing a given strategy, assuming all other players play according to the profile, is obtained using MixedStrategyProfile.strategy_value():

In [7]: p.strategy_value(g.players[0].strategies[2])
Out[7]: 1.0

A MixedBehaviorProfile object, which represents a probability distribution over the actions at each information set, is constructed using Game.mixed_behavior_profile(). Behavior profiles are initialized to uniform randomization over all actions at each information set.

Mixed behavior profiles are indexed similarly to mixed strategy profiles, except that indexing by a player returns a list of lists of probabilities, containing one list for each information set controlled by that player:

In [1]: g = gambit.Game.read_game("e02.efg")

In [2]: p = g.mixed_behavior_profile()

In [3]: list(p)
Out[3]: [0.5, 0.5, 0.5, 0.5, 0.5, 0.5]

In [5]: p[g.players[0]]
Out[5]: [[0.5, 0.5], [0.5, 0.5]]

In [6]: p[g.players[0].infosets[0]]
Out[6]: [0.5, 0.5]

In [7]: p[g.players[0].infosets[0].actions[0]]
Out[7]: 0.5

For games with a tree representation, a MixedStrategyProfile can be converted to its equivalent MixedBehaviorProfile by calling MixedStrategyProfile.as_behavior(). Equally, a MixedBehaviorProfile can be converted to an equivalent MixedStrategyProfile using MixedBehaviorProfile.as_strategy().

Computing Nash equilibria

Interfaces to algorithms for computing Nash equilibria are collected in the module gambit.nash. There are two choices for calling these algorithms: directly within Python, or via the corresponding Gambit command-line tool.

Calling an algorithm directly within Python has less overhead, which makes this approach well-suited to the analysis of smaller games, where the expected running time is small. In addition, these interfaces may offer more fine-grained control of the behavior of some algorithms.

Calling the Gambit command-line tool launches the algorithm as a separate process. This makes it easier to abort during the run of the algorithm (preserving where possible the equilibria which have already been found), and also makes the program more robust to any internal errors which may arise in the calculation.

Calling command-line tools

The interface to each command-line tool is encapsulated in a class with the word “External” in the name. These operate by creating a subprocess, which calls the corresponding Gambit command-line tool. Therefore, a working Gambit installation needs to be in place, with the command-line tools located in the executable search path.

Method Python class
gambit-enumpure ExternalEnumPureSolver
gambit-enummixed ExternalEnumMixedSolver
gambit-lp ExternalLPSolver
gambit-lcp ExternalLCPSolver
gambit-simpdiv ExternalSimpdivSolver
gambit-gnm ExternalGlobalNewtonSolver
gambit-enumpoly ExternalEnumPolySolver
gambit-liap ExternalLyapunovSolver
gambit-ipa ExternalIteratedPolymatrixSolver
gambit-logit ExternalLogitSolver

For example, consider the game e02.nfg from the set of standard Gambit examples. This game has a continuum of equilibria, in which the first player plays his first strategty with probability one, and the second player plays a mixed strategy, placing at least probability one-half on her first strategy:

In [1]: g = gambit.Game.read_game("e02.nfg")

In [2]: solver = gambit.nash.ExternalEnumPureSolver()

In [3]: solver.solve(g)
Out[3]: [[1.0, 0.0, 0.0, 1.0, 0.0]]

In [4]: solver = gambit.nash.ExternalEnumMixedSolver()

In [5]: solver.solve(g)
Out[5]: [[1.0, 0.0, 0.0, 1.0, 0.0], [1.0, 0.0, 0.0, 0.5, 0.5]]

In [6]: solver = gambit.nash.ExternalLogitSolver()

In [7]: solver.solve(g)
Out[7]: [[0.99999999997881173, 0.0, 2.1188267679986399e-11, 0.50001141005647654, 0.49998858994352352]]

In this example, the pure strategy solver returns the unique equilibrium in pure strategies. Solving using gambit-enummixed gives two equilibria, which are the extreme points of the set of equilibria. Solving by tracing the quantal response equilibrium correspondence produces a close numerical approximation to one equilibrium; in fact, the equilibrium which is the limit of the principal branch is the one in which the second player randomizes with equal probability on both strategies.

When a game’s representation is in extensive form, these solvers default to using the version of the algorithm which operates on the extensive game, where available, and returns a list of gambit.MixedBehaviorProfile objects. This can be overridden when calling solve() via the use_strategic parameter:

In [1]: g = gambit.Game.read_game("e02.efg")

In [2]: solver = gambit.nash.ExternalLCPSolver()

In [3]: solver.solve(g)
Out[3]: [<NashProfile for 'Selten (IJGT, 75), Figure 2': [1.0, 0.0, 0.5, 0.5, 0.5, 0.5]>]

In [4]: solver.solve(g, use_strategic=True)
Out[4]: [<NashProfile for 'Selten (IJGT, 75), Figure 2': [1.0, 0.0, 0.0, 1.0, 0.0]>]

As this game is in extensive form, in the first call, the returned profile is a MixedBehaviorProfile, while in the second, it is a MixedStrategyProfile. While the set of equilibria is not affected by whether behavior or mixed strategies are used, the equilibria returned by specific solution methods may differ, when using a call which does not necessarily return all equilibria.

Calling internally-linked libraries

Where available, versions of algorithms which have been linked internally into the Python library are generally called via convenience functions. The following table lists the algorithms available via this approach.

Method Python function
gambit-enumpure gambit.nash.enumpure_solve()
gambit-lp gambit.nash.lp_solve()
gambit-lcp gambit.nash.lcp_solve()

Parameters are available to modify the operation of the algorithm. The most common ones are use_strategic, to indicate the use of a strategic form version of an algorithm where both extensive and strategic versions are available, and rational, to indicate computation using rational arithmetic, where this is an option to the algorithm.

For example, taking again the game e02.efg as an example:

In [1]: g = gambit.Game.read_game("e02.efg")

In [2]: gambit.nash.lcp_solve(g)
Out[2]: [[1.0, 0.0, 0.5, 0.5, 0.5, 0.5]]

In [3]: gambit.nash.lcp_solve(g, rational=True)
Out[3]: [[Fraction(1, 1), Fraction(0, 1), Fraction(1, 2), Fraction(1, 2), Fraction(1, 2), Fraction(1, 2)]]

In [4]: gambit.nash.lcp_solve(g, use_strategic=True)
Out[4]: [[1.0, 0.0, 0.0, 1.0, 0.0]]

In [5]: gambit.nash.lcp_solve(g, use_strategic=True, rational=True)
Out[5]: [[Fraction(1, 1), Fraction(0, 1), Fraction(0, 1), Fraction(1, 1), Fraction(0, 1)]]

API documentation

Game representations

class gambit.Game

An object representing a game, in extensive or strategic form.

classmethod new_tree()

Creates a new Game consisting of a trivial game tree, with one node, which is both root and terminal, and no players.

classmethod new_table(dim)

Creates a new Game with a strategic representation.

Parameters:dim – A list specifying the number of strategies for each player.
classmethod from_arrays(*arrays)

Creates a new Game with a strategic representation. Each entry in arrays is a numpy array giving the payoff matrix for the corresponding player. The arrays must all have the same shape, and have the same number of dimensions as the total number of players.

classmethod read_game(fn)

Constructs a game from its serialized representation in a file. See Game representation formats for details on recognized formats.

Parameters:fn (file) – The path to the file to open
Raises:IOError – if the file cannot be opened, or does not contain a valid game representation
classmethod parse_game(s)

Constructs a game from its seralized representation in a string. See Game representation formats for details on recognized formats.

Parameters:s (str) – The string containing the serialized representation
Raises:IOError – if the string does not contain a valid game representation
is_tree

Returns True if the game has a tree representation.

title

Accesses the text string of the game’s title.

comment

Accesses the text string of the game’s comment.

actions

Returns a list-like object representing the actions defined in the game.

Raises:gambit.UndefinedOperationError – if the game does not have a tree representation.
infosets

Returns a list-like object representing the information sets defined in the game.

Raises:gambit.UndefinedOperationError – if the game does not have a tree representation.
players

Returns a Players collection object representing the players defined in the game.

strategies

Returns a list-like object representing the strategies defined in the game.

contingencies

Returns a collection object representing the collection of all possible pure strategy profiles in the game.

root

Returns the Node representing the root node of the game.

Raises:UndefinedOperationError if the game does not have a tree representation.
is_const_sum

Returns True if the game is constant sum.

is_perfect_recall

Returns True if the game is of perfect recall.

min_payoff

Returns the smallest payoff in any outcome of the game.

max_payoff

Returns the largest payoff in any outcome of the game.

__getitem__(profile)

Returns the Outcome associated with a profile of pure strategies.

Parameters:profile – A list of integers specifying the strategy number each player plays in the profile.
mixed_strategy_profile(rational=False)

Returns a mixed strategy profile MixedStrategyProfile over the game, initialized to uniform randomization for each player over his strategies. If the game has a tree representation, the mixed strategy profile is defined over the reduced strategic form representation.

Parameters:rational – If True, probabilities are represented using rational numbers; otherwise double-precision floating point numbers are used.
mixed_behavior_profile(rational=False)

Returns a behavior strategy profile MixedBehaviorProfile over the game, initialized to uniform randomization for each player over his actions at each information set.

Parameters:rational – If True, probabilities are represented using rational numbers; otherwise double-precision floating point numbers are used.
Raises:UndefinedOperationError – if the game does not have a tree representation.
write(format='native')

Returns a serialization of the game. Several output formats are supported, depending on the representation of the game.

  • efg: A representation of the game in the .efg extensive game file format. Not available for games in strategic representation.
  • nfg: A representation of the game in the .nfg strategic game file format. For an extensive game, this uses the reduced strategic form representation.
  • gte: The XML representation used by the Game Theory Explorer tool. Only available for extensive games.
  • native: The format most appropriate to the underlying representation of the game, i.e., efg or nfg.
class gambit.StrategicRestriction

A read-only view on a Game, defined by a subset of the strategies on the original game.

In addition to the members described here, a StrategicRestriction implements the interface of a Game, although operations which change the content of the game will raise an exception.

unrestrict()

Returns the Game object on which the restriction was based.

Representations of play of games

The main responsibility of these classes is to capture information about a plan of play of a game, by one or more players.

class gambit.StrategySupportProfile

A set-like object representing a subset of the strategies in a game. It incorporates the restriction that each player must have at least one strategy.

game

Returns the Game on which the support profile is defined.

issubset(other)

Returns True if this profile is a subset of other.

Parameters:other (StrategySupportProfile) – another support profile
issuperset(other)

Returns True if this profile is a superset of other.

Parameters:other (StrategySupportProfile) – another support profile
restrict()

Creates a StrategicRestriction object, which defines a restriction of the game in which only the strategies in this profile are present.

remove(strategy)

Modifies the support profile by removing the specified strategy.

Parameters:strategy (Strategy) – the strategy to remove
Raises:UndefinedOperationError – if attempting to remove the last strategy for a player
difference(other)

Returns a new support profile containing all the strategies which are present in this profile, but not in other.

Parameters:other (StrategySupportProfile) – another support profile
intersection(other)

Returns a new support profile containing all the strategies present in both this profile and in other.

Parameters:other (StrategySupportProfile) – another support profile
union(other)

Returns a new support profile containing all the strategies present in this profile, in other, or in both.

Parameters:other (StrategySupportProfile) – another support profile
class gambit.MixedStrategyProfile

Represents a mixed strategy profile over a Game.

__getitem__(index)

Returns a slice of the profile based on the parameter index.

  • If index is a Strategy, returns the probability with which that strategy is played in the profile.
  • If index is a Player, returns a list of probabilities, one for each strategy belonging to that player.
  • If index is an integer, returns the index th entry in the profile, treating the profile as a flat list of probabilities.
__setitem__(strategy, prob)

Sets the probability strategy is played in the profile to prob.

as_behavior()

Returns a behavior strategy profile BehavProfile associated to the profile.

Raises:gambit.UndefinedOperationError – if the game does not have a tree representation.
copy()

Creates a copy of the mixed strategy profile.

payoff(player)

Returns the expected payoff to a player if all players play according to the profile.

strategy_value(strategy)

Returns the expected payoff to choosing the strategy, if all other players play according to the profile.

strategy_values(player)

Returns the expected payoffs for a player’s set of strategies if all other players play according to the profile.

liap_value()

Returns the Lyapunov value (see [McK91]) of the strategy profile. The Lyapunov value is a non-negative number which is zero exactly at Nash equilibria.

class gambit.MixedBehaviorProfile

Represents a behavior strategy profile over a Game.

__getitem__(index)

Returns a slice of the profile based on the parameter index.

  • If index is a Action, returns the probability with which that action is played in the profile.
  • If index is an Infoset, returns a list of probabilities, one for each action belonging to that information set.
  • If index is a Player, returns a list of lists of probabilities, one list for each information set controlled by the player.
  • If index is an integer, returns the index th entry in the profile, treating the profile as a flat list of probabilities.
__setitem__(action, prob)

Sets the probability action is played in the profile to prob.

as_strategy()

Returns a MixedStrategyProfile which is equivalent to the profile.

belief(node)

Returns the probability node is reached, given its information set was reached.

belief(infoset)

Returns a list of belief probabilities of each node in infoset.

copy()

Creates a copy of the behavior strategy profile.

payoff(player)

Returns the expected payoff to player if all players play according to the profile.

payoff(action)

Returns the expected payoff to choosing action, conditional on having reached the information set, if all other players play according to the profile.

payoff(infoset)

Returns the expected payoff to the player who has the move at infoset, conditional on the information set being reached, if all players play according to the profile.

regret(action)

Returns the regret associated to action.

realiz_prob(infoset)

Returns the probability with which information set infoset is reached, if all players play according to the profile.

liap_value()

Returns the Lyapunov value (see [McK91]) of the strategy profile. The Lyapunov value is a non-negative number which is zero exactly at Nash equilibria.

Elements of games

These classes represent elements which exist inside of the definition of game.

class gambit.Rational

New in version 15.0.0.

Represents a rational number in specifying numerical data for a game, or in a computed strategy profile. This is implemented as a subclass of the Python standard library fractions.Fraction, with additional instrumentation for rendering in IPython notebooks.

class gambit.Players

A collection object representing the players in a game.

len()

Returns the number of players in the game.

__getitem__(i)

Returns player number i in the game. Players are numbered starting with 0.

chance

Returns the player representing all chance moves in the game.

add([label=""])

Add a Player to the game. If label is specified, sets the text label for the player. In the case of extensive games this will create a new player with no moves. In the case of strategic form games it creates a player with one strategy. If the provided player label is shared by another player a warning will be returned.

class gambit.Player

Represents a player in a Game.

game

Returns the Game in which the player is.

label

A text label useful for identification of the player.

number

Returns the number of the player in the Game. Players are numbered starting with 0.

is_chance

Returns True if the player object represents the chance player.

infosets

Returns a list-like object representing the information sets of the player.

strategies

Returns a gambit.Strategies collection object representing the strategies of the player.

min_payoff

Returns the smallest payoff for the player in any outcome of the game.

max_payoff

Returns the largest payoff for the player in any outcome of the game.

class gambit.Infoset

An information set for an extensive form game.

precedes(node)

Returns True or False depending on whether the specified node precedes the information set in the extensive game.

reveal(player)

Reveals the information set to a player.

actions

Returns a gambit.Actions collection object representing the actions defined in this information set.

label

A text label used to identify the information set.

is_chance

Returns True or False depending on whether this information set is associated to the chance player.

members

Returns the set of nodes associated with this information set.

player

Returns the player object associated with this information set.

class gambit.Actions

A collection object representing the actions available at an information set in a game.

len()

Returns the number of actions for the player.

__getitem__(i)

Returns action number i. Actions are numbered starting with 0.

add([action=None])

Add a Action to the list of actions of an information set.

class gambit.Action

An action associated with an information set.

delete()

Deletes this action from the game.

Raises:gambit.UndefinedOperationError – when the action is the last one of its infoset.
precedes(node)

Returns True if node precedes this action in the extensive game.

label

A text label used to identify the action.

infoset

Returns the information to which this action is associated.

prob

A settable property that represents the probability associated with the action. It can be a value stored as an int, gambit.Rational, or gambit.Decimal.

class gambit.Strategies

A collection object representing the strategies available to a player in a game.

len()

Returns the number of strategies for the player.

__getitem__(i)

Returns strategy number i. Strategies are numbered starting with 0.

add([label=""])

Add a Strategy to the player’s list of strategies.

Raises:TypeError – if called on a game which has an extensive representation.
class gambit.Strategy

Represents a strategy available to a Player.

label

A text label useful for identification of the strategy.

class gambit.Node

Represents a node in a Game.

is_successor_of(node)

Returns True if the node is a successor of node.

is_subgame_root(node)

Returns True if the current node is a root of a proper subgame.

label

A text label useful for identification of the node.

is_terminal

Returns True if the node is a terminal node in the game tree.

children

Returns a collection of the node’s children.

game

Returns the Game to which the node belongs.

infoset

Returns the Infoset associated with the node.

player

Returns the Player associated with the node.

parent

Returns the Node that is the parent of this node.

prior_action

Returns the action immediately prior to the node.

prior_sibling

Returns the Node that is prior to the node at the same level of the game tree.

next_sibling

Returns the Node that is the next node at the same level of the game tree.

outcome

Returns the Outcome that is associated with the node.

append_move(infoset[, actions])

Add a move to a terminal node, at the gambit.Infoset infoset. Alternatively, a gambit.Player can be passed as the information set, in which case the move is placed in a new information set for that player; in this instance, the number of actions at the new information set must be specified.

Raises:
insert_move(infoset[, actions])

Insert a move at a node, at the Infoset infoset. Alternatively, a Player can be passed as the information set, in which case the move is placed in a new information set for that player; in this instance, the number of actions at the new information set must be specified. The newly-inserted node takes the place of the node in the game tree, and the existing node becomes the first child of the new node.

Raises:
leave_infoset()

Removes this node from its information set. If this node is the last of its information set, this method does nothing.

delete_parent()

Deletes the parent node and its subtrees other than the one which contains this node and moves this node into its former parent’s place.

delete_tree()

Deletes the whole subtree which has this node as a root, except the actual node.

copy_tree(node)

Copies the subtree rooted at this node to node.

Raises:gambit.MismatchError – if both objects aren’t in the same game.
move_tree(node)

Move the subtree rooted at this node to node.

Raises:gambit.MismatchError – if both objects aren’t in the same game.
class gambit.Outcomes

A collection object representing the outcomes of a game.

len()

Returns the number of outcomes in the game.

__getitem__(i)

Returns outcome i in the game. Outcomes are numbered starting with 0.

add([label=""])

Add a Outcome to the game. If label is specified, sets the text label for the outcome. If the provided outcome label is shared by another outcome a warning will be returned.

class gambit.Outcome

Represents an outcome in a Game.

delete()

Deletes the outcome from the game.

label

A text label useful for identification of the outcome.

__getitem__(player)

Returns the payoff to player at the outcome. player may be a Player, a string, or an integer. If a string, returns the payoff to the player with that string as its label. If an integer, returns the payoff to player number player.

__setitem__(player, payoff)

Sets the payoff to the pl th player at the outcome to the specified payoff. Payoffs may be specified as integers or instances of gambit.Decimal or gambit.Rational. Players may be specified as in __getitem__().

Representation of errors and exceptions

exception gambit.MismatchError

A subclass of ValueError which is raised when attempting an operation among objects from different games.

exception gambit.UndefinedOperationError

A subclass of ValueError which is raised when an operation which is not well-defined is attempted.

Computation of Nash equilibria

gambit.nash.enumpure_solve(game, use_strategic=True, external=False)

Compute pure-strategy Nash equilibria of a game.

Parameters:
  • use_strategic (bool) – Use the strategic form. If False, computes agent-form pure-strategy equilibria, which treat only unilateral deviations at an individual information set
  • external (bool) – Call the external command-line solver instead of the internally-linked implementation
gambit.nash.lcp_solve(game, rational=True, use_strategic=False, external=False, stop_after=None, max_depth=None)

Compute Nash equilibria of a two-player game using linear complementarity programming.

Parameters:
  • rational (bool) – Compute using rational precision (more precise, often much slower)
  • use_strategic (bool) – Use the strategic form version even for extensive games
  • external (bool) – Call the external command-line solver instead of the internally-linked implementation
  • stop_after (int) – Number of equilibria to contribute (default is to compute until all reachable equilbria are found)
  • max_depth (int) – Maximum recursion depth (default is no limit)
Raises:

RuntimeError – if game has more than two players.
gambit.nash.lp_solve(game, rational=True, use_strategic=False, external=False)

Compute Nash equilibria of a two-player constant-sum game using linear programming.

Parameters:
  • rational (bool) – Compute using rational precision (more precise, often much slower)
  • use_strategic (bool) – Use the strategic form version even for extensive games
  • external (bool) – Call the external command-line solver instead of the internally-linked implementation
Raises:

RuntimeError – if game has more than two players.