burlap.behavior.stochasticgames

Class GameAnalysis

java.lang.Object

burlap.behavior.stochasticgames.GameAnalysis

public class GameAnalysis
extends java.lang.Object

This class provides a means to record all the interactions in a stochastic game; specifically, the sequence of states, joint actions taken, and joint reward received. It also has methods to converting everything to a string/file and parsing a string/file back into this object so that results can be recorded and saved to disk.

This class should be used either by constructing with an initial state (GameAnalysis(State)) or by constructing with the default constructor and then using the initializeGameWithInitialState(State) method before recording any further transitions. Transitions should then be recorded with the recordTransitionTo(JointAction, State, Map) method which takes as input the next state to which the agent transtions, the joint action taken in the previously recorded state that causes the transition, and the joint reward received for the transition.

When querying about the state, joint action, or joint rewards, use the methods getState(int), getJointAction(int), and getJointReward(int) respectively. These methods take as input the time step of the element you want. Note that t = 0 refers to the initial state step so calling getState(0) and getJointAction(0) will return the initial state and the joint action taken in the initial state, respectively. However, joint rewards are always received in the next time step from the state and action that produced them. Therefore, getJointReward(0) is undefined. Instead, the first reward received will be at time step 1: getReward(1). Additionally, the action and reward for a specific agent in a specific time step can be queried with getActionForAgent(int, String) and getRewardForAgent(int, String), respectively.

Author:

James MacGlashan

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Set<java.lang.String>	agentsInvolvedInGame The set of agents involved in this game
java.util.List<JointAction>	jointActions The sequence of joint actions
java.util.List<java.util.Map<java.lang.String,java.lang.Double>>	jointRewards The sequence of joint rewards
java.util.List<State>	states The sequence of states

Constructor Summary

Constructors

Constructor and Description
GameAnalysis() Initialzes the datastructures.
GameAnalysis(State initialState) Initializes with an initial state of the game.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	agentIsInvolvedInGame(java.lang.String agentName) Returns true if an agent with the given name took any actions in the course of this game.
GroundedSGAgentAction	getActionForAgent(int t, java.lang.String agentName) Returns the action taken for the given agent at the given time step where t=0 refers to the joint action taken in the initial state.
java.util.Set<java.lang.String>	getAgentsInvolvedInGame() Returns the set of agents involved in this game
JointAction	getJointAction(int t) Returns the joint action taken in time step t where t=0 refers to the joint action taken in the initial state.
java.util.List<JointAction>	getJointActions() Returns the joint action sequence list object
java.util.Map<java.lang.String,java.lang.Double>	getJointReward(int t) Returns the joint reward received in time step t.
java.util.List<java.util.Map<java.lang.String,java.lang.Double>>	getJointRewards() Returns the joint reward sequence list object
double	getRewardForAgent(int t, java.lang.String agentName) Returns the reward received for the agent with the given name at the given step.
State	getState(int t) Returns the state stored at time step t where t=0 refers to the initial state
java.util.List<State>	getStates() Returns the state sequence list object
protected void	initializeDatastructures() Instantiates the datastructures of this object.
void	initializeGameWithInitialState(State initialState) Clears out any already recorded states, joint actions, and rewards, and sets the initial state of the game.
static GameAnalysis	legacyParseFileIntoGA(java.lang.String path, SGDomain domain, StateParser sp) Using the legacy BURLAP 1.0 format, reads a game that was written to a file and turns into a GameAnalysis object.
static GameAnalysis	legacyParseStringIntoGameAnalysis(java.lang.String str, SGDomain domain, StateParser sp) Using the legacy BURLAP 1.0 GameAnalysis format, parses a string representing a GameAnalysis object into an actual GameAnalysis object.
static void	main(java.lang.String[] args)
int	maxTimeStep() Returns the max time step index in this game which equals numTimeSteps()-1.
int	numTimeSteps() Returns the number of time steps recorded which is equal to the number of states observed.
static GameAnalysis	parseFileIntoGA(java.lang.String path, SGDomain domain) Reads a game that was written to a file and turns into a GameAnalysis object.
static GameAnalysis	parseGame(SGDomain domain, java.lang.String episodeString)
void	recordTransitionTo(JointAction jointAction, State nextState, java.util.Map<java.lang.String,java.lang.Double> jointReward) Records a transition from the last recorded state in this object using the specififed joint action to the specified next state and with the specified joint reward being recieved as a result.
java.lang.String	serialize()
java.lang.String	serialize(SerializableStateFactory serializableStateFactory)
void	writeToFile(java.lang.String path) Writes this game to a file.
void	writeToFile(java.lang.String path, SerializableStateFactory serializableStateFactory) Writes this game to a file.

Methods inherited from class java.lang.Object

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

Field Detail

states

public java.util.List<State> states

The sequence of states

jointActions

public java.util.List<JointAction> jointActions

The sequence of joint actions

jointRewards

public java.util.List<java.util.Map<java.lang.String,java.lang.Double>> jointRewards

The sequence of joint rewards

agentsInvolvedInGame

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

The set of agents involved in this game

Constructor Detail

GameAnalysis

public GameAnalysis()

Initialzes the datastructures. Note that the method initializeGameWithInitialState(State) should be called to set the initial state of the game before any transitions are recorded.

GameAnalysis

public GameAnalysis(State initialState)

Initializes with an initial state of the game.

Parameters:

initialState - the initial state of the game.

Method Detail

initializeGameWithInitialState

public void initializeGameWithInitialState(State initialState)

Clears out any already recorded states, joint actions, and rewards, and sets the initial state of the game.

Parameters:

initialState - the initial state of the game.

initializeDatastructures

protected void initializeDatastructures()

Instantiates the datastructures of this object.

getState

public State getState(int t)

Returns the state stored at time step t where t=0 refers to the initial state

Parameters:

t - the time step

Returns:

the state at time step t

getJointAction

public JointAction getJointAction(int t)

Returns the joint action taken in time step t where t=0 refers to the joint action taken in the initial state.

Parameters:

t - the time step

Returns:

the joint action taken in time step t

getJointReward

public java.util.Map<java.lang.String,java.lang.Double> getJointReward(int t)

Returns the joint reward received in time step t. Note that rewards are always returned in the time step after the joint action that generated them; therefore, this method is undefined for t = 0. Instead, the first time step with a reward is t=1 which refers to the joint reward received after the first joint action is taken in the initial state.

Parameters:

t - the time step

Returns:

the joint reward received at time step t

getActionForAgent

public GroundedSGAgentAction getActionForAgent(int t,
                                      java.lang.String agentName)

Returns the action taken for the given agent at the given time step where t=0 refers to the joint action taken in the initial state. if there is no action taken by the agent with the given name, then a runtime exception is thrown.

Parameters:

t - the time step

agentName - the name of the agent

Returns:

the action taken by the specified agent in the given time step

getRewardForAgent

public double getRewardForAgent(int t,
                       java.lang.String agentName)

Returns the reward received for the agent with the given name at the given step. Note that rewards are always returned in the time step after the joint action that generated them; therefore, this method is undefined for t = 0. Instead, the first time step with a reward is t=1 which refers to the reward received after the first joint action is taken in the initial state.

Parameters:

t - the time step

agentName - the name of the agent

Returns:

the reward received by the agent

agentIsInvolvedInGame

public boolean agentIsInvolvedInGame(java.lang.String agentName)

Returns true if an agent with the given name took any actions in the course of this game.

Parameters:

agentName - the name of the agent

Returns:

true if the agent took an action in this game; false otherwise.

numTimeSteps

public int numTimeSteps()

Returns the number of time steps recorded which is equal to the number of states observed.

Returns:

the number of time steps recorded.

maxTimeStep

public int maxTimeStep()

Returns the max time step index in this game which equals numTimeSteps()-1.

Returns:

the max time step index in this game

recordTransitionTo

public void recordTransitionTo(JointAction jointAction,
                      State nextState,
                      java.util.Map<java.lang.String,java.lang.Double> jointReward)

Records a transition from the last recorded state in this object using the specififed joint action to the specified next state and with the specified joint reward being recieved as a result.

Parameters:

jointAction - the joint action taken in the last recorded state in this object

nextState - the next state to which the agents transition

jointReward - the joint reward received for the transiton

getStates

public java.util.List<State> getStates()

Returns the state sequence list object

Returns:

the state sequence list object

getJointActions

public java.util.List<JointAction> getJointActions()

Returns the joint action sequence list object

Returns:

the joint action sequence list object

getJointRewards

public java.util.List<java.util.Map<java.lang.String,java.lang.Double>> getJointRewards()

Returns the joint reward sequence list object

Returns:

the joint reward sequence list object

getAgentsInvolvedInGame

public java.util.Set<java.lang.String> getAgentsInvolvedInGame()

Returns the set of agents involved in this game

Returns:

the set of agents involved in this game

serialize

public java.lang.String serialize()

serialize

public java.lang.String serialize(SerializableStateFactory serializableStateFactory)

parseGame

public static GameAnalysis parseGame(SGDomain domain,
                     java.lang.String episodeString)

writeToFile

public void writeToFile(java.lang.String path)

Writes this game to a file. If the the directory for the specified file path do not exist, then they will be created. If the file extension is not ".game" will automatically be added. States will be serialized with SerializableStateFactory

Parameters:

path - the path to the file in which to write this game.

writeToFile

public void writeToFile(java.lang.String path,
               SerializableStateFactory serializableStateFactory)

Writes this game to a file. If the the directory for the specified file path do not exist, then they will be created. If the file extension is not ".game" will automatically be added.

Parameters:

path - the path to the file in which to write this game.

serializableStateFactory - the SerializableStateFactory used to serialize states.

parseFileIntoGA

public static GameAnalysis parseFileIntoGA(java.lang.String path,
                           SGDomain domain)

Reads a game that was written to a file and turns into a GameAnalysis object.

Parameters:

path - the path to the game file.

domain - the stochastic games domain to which the states and actions belong

Returns:

an GameAnalysis object.

legacyParseStringIntoGameAnalysis

public static GameAnalysis legacyParseStringIntoGameAnalysis(java.lang.String str,
                                             SGDomain domain,
                                             StateParser sp)

Using the legacy BURLAP 1.0 GameAnalysis format, parses a string representing a GameAnalysis object into an actual GameAnalysis object.

Parameters:

str - the string representation

domain - the stochastic games domain to which the actions belong

sp - the state parser used to represent states

Returns:

a GameAnalysis object.

legacyParseFileIntoGA

public static GameAnalysis legacyParseFileIntoGA(java.lang.String path,
                                 SGDomain domain,
                                 StateParser sp)

Using the legacy BURLAP 1.0 format, reads a game that was written to a file and turns into a GameAnalysis object.

Parameters:

path - the path to the game file.

domain - the stochastic games domain to which the states and actions belong

sp - a state parser that can parse the state string representation in the file

Returns:

an GameAnalysis object.

main

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