burlap.domain.stochasticgames.normalform

Class SingleStageNormalFormGame

java.lang.Object

burlap.domain.stochasticgames.normalform.SingleStageNormalFormGame

All Implemented Interfaces:

DomainGenerator

public class SingleStageNormalFormGame
extends java.lang.Object
implements DomainGenerator

This stochastic game domain generator provides methods to create N-player single stage games. The method generateAgentType(int) will generate the agent type (set of actions) for the given player number.

In addition to this generator being able to return the domain object, it may also be used to return the corresponding joint reward function with the method getJointRewardFunction().

This class also provides static methods for returning generators for a number of classic bimatrix games: prisoner's dilemma, chicken, hawk dove, battle of the sexes 1, battle of the sexes 2, matching pennies, and stag hunt.

This class also has a method for streamlining the world creation process so that repeated games (or single shot games) can be easily played in the constructed game. For this use either the createRepeatedGameWorld(SGAgent...) or createRepeatedGameWorld(SGDomain, SGAgent...) method. The former method will create an new domain instance using the generateDomain() method; the latter will use an already generated version of the domain that you provide to it.

Finally, this class's payout function definition (and other properties) can be modified without affecting previously generated domains or payout functions, allowing it to be reused multiple times.

Author:

James MacGlashan

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	SingleStageNormalFormGame.ActionNameMap A wrapper for a HashMap from strings to ints used to map action names to their action index.
static class	SingleStageNormalFormGame.AgentPayoutFunction A class for defining a payout function for a single agent for each possible strategy profile.
static class	SingleStageNormalFormGame.MatrixAction
protected static class	SingleStageNormalFormGame.SingleStageNormalFormJointRewardFunction A Joint Reward Function class that uses the parent domain generators payout matrix to determine payouts for any given strategy profile.
static class	SingleStageNormalFormGame.StrategyProfile A strategy profile represented as an array of action indices that is hashable.

Field Summary

Fields

Modifier and Type	Field and Description
protected SingleStageNormalFormGame.ActionNameMap[]	actionNameToIndex Returns the the int index of an action for a given name for each player
protected java.util.List<java.util.List<java.lang.String>>	actionSets The ordered action set for each player
static java.lang.String	BIMATRIX_ACTION_BASE_NAME When this generator is constructed with a generic bimatrix or zero sum definition (SingleStageNormalFormGame(String[][], double[][][]) or SingleStageNormalFormGame(String[][]), respectively), action names for each row/column will take the form of: BIMATRIX_ACTION_BASE_NAMEi where i is the row/column index.
protected int	nPlayers Number of players
protected SingleStageNormalFormGame.AgentPayoutFunction[]	payouts The pay out function for each player.
protected java.util.Set<java.lang.String>	uniqueActionNames The unique action names for the domain to be generated.

Constructor Summary

Constructors

Constructor and Description
SingleStageNormalFormGame(double[][] zeroSumRowPayoff) A constructor for a bimatrix zero sum game.
SingleStageNormalFormGame(double[][] rowPayoff, double[][] colPayoff) A constructor for a bimatrix game where the row player payoffs and column player payoffs are provided in two different 2D double matrices.
SingleStageNormalFormGame(java.util.List<java.util.List<java.lang.String>> actionSets) A constructor for games with an asymmetric number of actions for each player.
SingleStageNormalFormGame(java.lang.String[][] actionSets) A constructor for games with a symmetric number of actions for each player.
SingleStageNormalFormGame(java.lang.String[][] actionSets, double[][][] twoPlayerPayoutMatrix) A constructor for bimatrix games with specified action names.

Method Summary

Modifier and Type	Method and Description
int	actionIndex(int pn, java.lang.String actionName) Returns the action index of the action named actionName of player pn
java.lang.String	actionName(int pn, int an) Returns the name of the an action of player pn
World	createRepeatedGameWorld(SGAgent... agents) Creates a world instance for this game in which the provided agents join in the order they are passed.
World	createRepeatedGameWorld(SGDomain domain, SGAgent... agents) Creates a world instance for this game in which the provided agents join in the order they are passed.
SGAgentType	generateAgentType(int player)
Domain	generateDomain() Returns a newly instanced Domain object
static SingleStageNormalFormGame	getBattleOfTheSexes1() Returns an instance of Battle of the Sexes 1, which is defined by:
static SingleStageNormalFormGame	getBattleOfTheSexes2() Returns an instance of Battle of the Sexes 2, which is defined by:
static SingleStageNormalFormGame	getChicken() Returns an instance of Chicken, which is defined by:
static SingleStageNormalFormGame	getHawkDove() Returns an instance of Hawk Dove, which is defined by:
JointRewardFunction	getJointRewardFunction() Returns a JointRewardFunction function for this game.
static SingleStageNormalFormGame	getMatchingPennies() Returns an instance of Matching Pennies, which is defined by:
int	getNumPlayers() Returns the number of players in the domain to be generated
double	getPayout(int pn, int... actions) Returns the payout that player pn receives for the given strategy profile.
double	getPayout(int pn, java.lang.String... actions) Returns the payout that player pn receives for the given strategy profile.
static SingleStageNormalFormGame	getPrisonersDilemma() Returns an instance of Prisoner's Dilemma, which is defined by:
static JointModel	getRepatedGameActionModel() Returns a repeated game joint action model.
static SingleStageNormalFormGame	getStagHunt() Returns an instance of Stag Hunt, which is defined by:
protected static SingleStageNormalFormGame.StrategyProfile	getStrategyProfile(SingleStageNormalFormGame.ActionNameMap[] actionNameToIndex, java.lang.String... actions) Returns a hashable strategy profile object for a strategy profile specified by action names
static void	main(java.lang.String[] args) A main method showing example code that would be used to create an instance of Prisoner's dilemma and begin playing it with a SGWorldShell.
void	setPayout(int playerNumber, double payout, int... actions) Sets the pay out that player number playerNumber receives for a given strategy profile
void	setPayout(int playerNumber, double payout, java.lang.String... actions) Sets the pay out that player number playerNumber receives for a given strategy profile

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BIMATRIX_ACTION_BASE_NAME

public static final java.lang.String BIMATRIX_ACTION_BASE_NAME

When this generator is constructed with a generic bimatrix or zero sum definition (SingleStageNormalFormGame(String[][], double[][][]) or SingleStageNormalFormGame(String[][]), respectively), action names for each row/column will take the form of: BIMATRIX_ACTION_BASE_NAMEi where i is the row/column index. More specifically, it will be "actioni", since BIMATRIX_ACTION_BASE_NAME = "action"

See Also:

Constant Field Values

nPlayers

protected int nPlayers

Number of players

actionSets

protected java.util.List<java.util.List<java.lang.String>> actionSets

The ordered action set for each player

payouts

protected SingleStageNormalFormGame.AgentPayoutFunction[] payouts

The pay out function for each player. This each element of the array takes SingleStageNormalFormGame.StrategyProfile objects as input to return the pay out for the player at the given index in the array.

actionNameToIndex

protected SingleStageNormalFormGame.ActionNameMap[] actionNameToIndex

Returns the the int index of an action for a given name for each player

uniqueActionNames

protected java.util.Set<java.lang.String> uniqueActionNames

The unique action names for the domain to be generated.

Constructor Detail

SingleStageNormalFormGame

public SingleStageNormalFormGame(java.lang.String[][] actionSets,
                                 double[][][] twoPlayerPayoutMatrix)

A constructor for bimatrix games with specified action names.

Parameters:

actionSets - a 2x2 array of strings giving the names for each action. actionSets[0][1] returns the name of the second action for the first player.

twoPlayerPayoutMatrix - A 2x2x2 payout matrix. twoPlayerPayoutMatrix[0][0][1] gives the payout player 1 receives when player takes its first action and player two takes its second action.

SingleStageNormalFormGame

public SingleStageNormalFormGame(double[][] rowPayoff,
                                 double[][] colPayoff)

A constructor for a bimatrix game where the row player payoffs and column player payoffs are provided in two different 2D double matrices. The action names for each row/column will be named "action0" ... "actionN" where N is the maximum number of rows/columns.

Parameters:

rowPayoff - the payoff matrix for the row player

colPayoff - the payoff matrix for the column player

SingleStageNormalFormGame

public SingleStageNormalFormGame(double[][] zeroSumRowPayoff)

A constructor for a bimatrix zero sum game. The action names for each row/column will be named "action0" ... "actionN" where N is the maximum number of rows/columns.

Parameters:

zeroSumRowPayoff - the payoffs for the row player

SingleStageNormalFormGame

public SingleStageNormalFormGame(java.lang.String[][] actionSets)

A constructor for games with a symmetric number of actions for each player. The payoffs will not be set.

Parameters:

actionSets - an nxm matrix specifying the m actions names for each of the n players. actionSets[i][j] specifies the jth action name for player i

SingleStageNormalFormGame

public SingleStageNormalFormGame(java.util.List<java.util.List<java.lang.String>> actionSets)

A constructor for games with an asymmetric number of actions for each player.

Parameters:

actionSets - the oredered list of actions for each player. actionSets.get(i).get(j) returns the name of the jth action for the ith player.

Method Detail

setPayout

public void setPayout(int playerNumber,
                      double payout,
                      java.lang.String... actions)

Sets the pay out that player number playerNumber receives for a given strategy profile

Parameters:

playerNumber - the index of the player whose payout should be specified (index starts at 0)

payout - the payout the playerNumberth receives

actions - the strategy profile; array specifying the names of the actions taken by each player, ordered by their player number

setPayout

public void setPayout(int playerNumber,
                      double payout,
                      int... actions)

Sets the pay out that player number playerNumber receives for a given strategy profile

Parameters:

playerNumber - the index of the player whose payout should be specified (index starts at 0)

payout - the payout the playerNumberth receives

actions - the strategy profile; array specifying the int index of the actions taken by each player, ordered by their player number

actionName

public java.lang.String actionName(int pn,
                                   int an)

Returns the name of the an action of player pn

Parameters:

pn - the player number

an - the action index

Returns:

the name of the an action of player pn

actionIndex

public int actionIndex(int pn,
                       java.lang.String actionName)

Returns the action index of the action named actionName of player pn

Parameters:

pn - the player number

actionName - the name of the action

Returns:

the action index of the action named actionName of player pn

getPayout

public double getPayout(int pn,
                        java.lang.String... actions)

Returns the payout that player pn receives for the given strategy profile.

Parameters:

pn - the player number

actions - the strategy profile specified as an array of action names, ordered by the player number of the player that took the action.

Returns:

the payout that player pn receives for the given strategy profile.

getPayout

public double getPayout(int pn,
                        int... actions)

Returns the payout that player pn receives for the given strategy profile.

Parameters:

pn - the player number

actions - the strategy profile specified as an array of action indices, ordered by the player number of the player that took the action.

Returns:

the payout that player pn receives for the given strategy profile.

getNumPlayers

public int getNumPlayers()

Returns the number of players in the domain to be generated

Returns:

the number of players in the domain to be generated

generateDomain

public Domain generateDomain()

Description copied from interface: DomainGenerator

Returns a newly instanced Domain object

Specified by:

generateDomain in interface DomainGenerator

Returns:

the newly instantiated Domain object.

createRepeatedGameWorld

public World createRepeatedGameWorld(SGAgent... agents)

Creates a world instance for this game in which the provided agents join in the order they are passed.

Parameters:

agents - the agents to join the created world.

Returns:

a world instance with the provided agents having already joined.

createRepeatedGameWorld

public World createRepeatedGameWorld(SGDomain domain,
                                     SGAgent... agents)

Creates a world instance for this game in which the provided agents join in the order they are passed. This object uses the provided domain instance generated from this object instead of generating a new one.

Parameters:

domain - the SGDomain instance

agents - the agents to join the created world.

Returns:

a world instance with the provided agents having already joined.

getJointRewardFunction

public JointRewardFunction getJointRewardFunction()

Returns a JointRewardFunction function for this game.

Returns:

a JointRewardFunction function for this game.

getStrategyProfile

protected static SingleStageNormalFormGame.StrategyProfile getStrategyProfile(SingleStageNormalFormGame.ActionNameMap[] actionNameToIndex,
                                                                              java.lang.String... actions)

Returns a hashable strategy profile object for a strategy profile specified by action names

Parameters:

actionNameToIndex - the map from action names to action indices

actions - the strategy profile specified as an array of action names, ordered by the player number of the player that took the action.

Returns:

a hashable strategy profile.

generateAgentType

public SGAgentType generateAgentType(int player)

getRepatedGameActionModel

public static JointModel getRepatedGameActionModel()

Returns a repeated game joint action model. This action model always returns to the same state.

Returns:

a repeated game joint action model.

getPrisonersDilemma

public static SingleStageNormalFormGame getPrisonersDilemma()

Returns an instance of Prisoner's Dilemma, which is defined by:

(3,3); (0,5)

(5,0); (1,1)

Returns:

and instance of Prisoner's Dilemma.

getChicken

public static SingleStageNormalFormGame getChicken()

Returns an instance of Chicken, which is defined by:

(0,0); (-1,1)

(1,-1); (-10,-10)

Returns:

and instance of Chicken.

getHawkDove

public static SingleStageNormalFormGame getHawkDove()

Returns an instance of Hawk Dove, which is defined by:

(-1,-1); (2,0)

(0,2); (1,1)

Returns:

and instance of Hawk Dove.

getBattleOfTheSexes1

public static SingleStageNormalFormGame getBattleOfTheSexes1()

Returns an instance of Battle of the Sexes 1, which is defined by:

(3,2); (0,0)

(0,0); (2,3)

Returns:

and instance of Battle of the Sexes 1.

getBattleOfTheSexes2

public static SingleStageNormalFormGame getBattleOfTheSexes2()

Returns an instance of Battle of the Sexes 2, which is defined by:

(3,2); (1,1)

(0,0); (2,3)

Returns:

and instance of Battle of the Sexes 2.

getMatchingPennies

public static SingleStageNormalFormGame getMatchingPennies()

Returns an instance of Matching Pennies, which is defined by:

(1,-1); (-1,1)

(-1,1); (1,-1)

Returns:

and instance of Matching Pennies.

getStagHunt

public static SingleStageNormalFormGame getStagHunt()

Returns an instance of Stag Hunt, which is defined by:

(2,2); (0,1)

(1,0); (1,1)

Returns:

and instance of Stag Hunt.

main

public static void main(java.lang.String[] args)

A main method showing example code that would be used to create an instance of Prisoner's dilemma and begin playing it with a SGWorldShell.

Parameters:

args - command line args