burlap.oomdp.singleagent

Class Action

java.lang.Object

burlap.oomdp.singleagent.Action

Direct Known Subclasses:

BlockDude.MoveAction, BlockDude.MoveUpAction, BlockDude.PickupAction, BlockDude.PutdownAction, BlocksWorld.StackAction, BlocksWorld.UnstackAction, CartPoleDomain.MovementAction, FrostbiteDomain.ActionIdle, FrostbiteDomain.MovementAction, GraphDefinedDomain.GraphAction, GridWorldDomain.MovementAction, InvertedPendulum.ForceAction, LunarLanderDomain.ActionIdle, LunarLanderDomain.ActionThrust, LunarLanderDomain.ActionTurn, ModeledDomainGenerator.ModeledAction, ModeledDomainGenerator.RMaxStateAction, NullAction, Option, RLGlueWrappedDomainGenerator.RLGlueActionWrapper, SGToSADomain.SAActionWrapper, TabulatedDomainWrapper.ActionWrapper

public abstract class Action
extends java.lang.Object

Abstract class for defining what happens when an action is executed in a state. The method getTransitions(burlap.oomdp.core.State, String[]) is what defines the transition dynamics of the MDP for this action. If this method is not overridden by subclasses, then an UnsupportedOperation exception is thrown . If the domain being created is only going to be used planning/learning algorithms that require a generative model, rather than the fully enumerated transition dynamics, then the getTransitions(burlap.oomdp.core.State, String[]) does not need to be implemented, but for full robustness it should be. If your domain is deterministic, you can trivially implement it by having it return a call to the deterministicTransition(burlap.oomdp.core.State, String[]) method, which will wrap the result of a performAction(burlap.oomdp.core.State, String[])} method with a 1.0 outcome probability TransitionProbability object and insert it in a list containing just that element.

Action objects may also be defined to require object parameters (which must adhere to a type). Parameters can also have parameter order groups specified if there is effect symmetry when changing the order of the parameters. That is, if you swapped the parameter assignments for parameters in the same order group, the action would have the same effect. However, if you swapped the parameter assignments of two parameters in different order groups, the action would have a different effect. For more information on parameter order groups, see its discussion in the PropositionalFunction class description.

Author:

James MacGlashan

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<ActionObserver>	actionObservers An observer that will be notified of an actions results every time it is executed.
protected Domain	domain The domain with which this action is associated
protected java.lang.String	name The name of the action that can uniquely identify it
protected java.lang.String[]	parameterClasses The object classes each parameter of this action can accept; empty list for a parameter-less action (which is the default)
protected java.lang.String[]	parameterOrderGroup Specifies the parameter order group each parameter.

Constructor Summary

Constructors

Constructor and Description
Action()
Action(java.lang.String name, Domain domain, java.lang.String parameterClasses) Initializes the action with the name of the action, the domain to which it belongs, and the parameters it takes.
Action(java.lang.String name, Domain domain, java.lang.String[] parameterClasses) Initializes the action with the name of the action, the domain to which it belongs, and the parameters it takes.
Action(java.lang.String name, Domain domain, java.lang.String[] parameterClasses, java.lang.String[] parameterOrderGroups) Initializes the action with the name of the action, the domain to which it belongs, the parameters it takes, and the parameter order groups.

Method Summary

Methods

Modifier and Type	Method and Description
void	addActionObserver(ActionObserver observer) Sets an action observer for this action.
boolean	applicableInState(State s, java.lang.String params) Returns true if this action can be applied in this specified state with the specified parameters.
boolean	applicableInState(State s, java.lang.String[] params) Returns true if this action can be applied in this specified state with the specified parameters.
void	clearAllActionsObservers() Clears all action observers associated with this action
protected java.util.List<TransitionProbability>	deterministicTransition(State s, java.lang.String[] params) Returns the transition dynamics by assuming the action to be deterministic and wrapping the result of a performAction(burlap.oomdp.core.State, String[]) method with a 1.0 probable TransitionProbability object and inserting it in the returned list.
boolean	equals(java.lang.Object obj)
java.util.List<GroundedAction>	getAllApplicableGroundedActions(State s) Returns all possible groundings of this action that can be applied in the provided State.
static java.util.List<GroundedAction>	getAllApplicableGroundedActionsFromActionList(java.util.List<Action> actions, State s) Returns all GroundedActions that are applicable in the given State for all Action objects in the provided list.
Domain	getDomain() Returns the domain to which this action belongs.
java.lang.String	getName() Returns the name of the action
java.lang.String[]	getParameterClasses() Returns a String array of the names of of the object classes to which bound parameters must belong
java.lang.String[]	getParameterOrderGroups() Returns the a String array specifying the parameter order group of each parameter.
java.util.List<TransitionProbability>	getTransitions(State s, java.lang.String params) Returns the transition probabilities for applying this action in the given state with the given set of parameters.
java.util.List<TransitionProbability>	getTransitions(State s, java.lang.String[] params) Returns the transition probabilities for applying this action in the given state with the given set of parameters.
int	hashCode()
protected void	init(java.lang.String name, Domain domain, java.lang.String[] parameterClasses, java.lang.String[] parameterOrderGroups)
boolean	isPrimitive() Returns whether this action is a primitive action of the domain or not.
boolean	parametersAreObjects() Returns true if all parameters (if any) for this action represent OO-MDP objects in a state; false otherwise.
State	performAction(State s, java.lang.String params) Performs this action in the specified state using the specified parameters and returns the resulting state.
State	performAction(State s, java.lang.String[] params) Performs this action in the specified state using the specified parameters and returns the resulting state.
protected abstract State	performActionHelper(State s, java.lang.String[] params) This method determines what happens when an action is applied in the given state with the given parameters.

Methods inherited from class java.lang.Object

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

Field Detail

name

protected java.lang.String name

The name of the action that can uniquely identify it

domain

protected Domain domain

The domain with which this action is associated

parameterClasses

protected java.lang.String[] parameterClasses

The object classes each parameter of this action can accept; empty list for a parameter-less action (which is the default)

parameterOrderGroup

protected java.lang.String[] parameterOrderGroup

Specifies the parameter order group each parameter. Parameters in the same order group are order invariant; that is, if you swapped the parameter assignments for for parameters in the same group, the action would have the same effect. However, if you swapped the parameter assignments of two parameters in different order groups, the action would have a different effect.

actionObservers

protected java.util.List<ActionObserver> actionObservers

An observer that will be notified of an actions results every time it is executed. By default no observer is specified.

Constructor Detail

Action

public Action()

Action

public Action(java.lang.String name,
      Domain domain,
      java.lang.String parameterClasses)

Initializes the action with the name of the action, the domain to which it belongs, and the parameters it takes. The action will also be automatically be added to the domain. The parameter order group is set to be a unique order group for each parameter.

Parameters:

name - the name of the action

domain - the domain to which the action belongs

parameterClasses - a comma delineated String of the names of the object classes to which bound parameters must belong

Action

public Action(java.lang.String name,
      Domain domain,
      java.lang.String[] parameterClasses)

Initializes the action with the name of the action, the domain to which it belongs, and the parameters it takes. The action will also be automatically be added to the domain. The parameter order group is set to be a unique order group for each parameter.

Parameters:

name - the name of the action

domain - the domain to which the action belongs

parameterClasses - a String array of the names of the object classes to which bound parameters must belong

Action

public Action(java.lang.String name,
      Domain domain,
      java.lang.String[] parameterClasses,
      java.lang.String[] parameterOrderGroups)

Initializes the action with the name of the action, the domain to which it belongs, the parameters it takes, and the parameter order groups. The action will also be automatically be added to the domain.

Parameters:

name - the name of the action

domain - the domain to which the action belongs

parameterClasses - a String array of the names of the object classes to which bound parameters must belong

parameterOrderGroups - the order group assignments for each of the parameters.

Method Detail

init

protected void init(java.lang.String name,
        Domain domain,
        java.lang.String[] parameterClasses,
        java.lang.String[] parameterOrderGroups)

getName

public final java.lang.String getName()

Returns the name of the action

Returns:

the name of the action

getParameterClasses

public final java.lang.String[] getParameterClasses()

Returns a String array of the names of of the object classes to which bound parameters must belong

Returns:

a String array of the names of of the object classes to which bound parameters must belong. The array is empty if this action does not require parameters.

getParameterOrderGroups

public final java.lang.String[] getParameterOrderGroups()

Returns the a String array specifying the parameter order group of each parameter.

Returns:

the a String array specifying the parameter order group of each parameter. The array is empty if this action does not require parameters.

parametersAreObjects

public boolean parametersAreObjects()

Returns true if all parameters (if any) for this action represent OO-MDP objects in a state; false otherwise. The default behavior is to return True; but this can be overriden for special actions.

Returns:

true if all parameters (if any) for this action represent OO-MDP objects in a state; false otherwise.

getDomain

public final Domain getDomain()

Returns the domain to which this action belongs.

Returns:

the domain to which this action belongs.

addActionObserver

public void addActionObserver(ActionObserver observer)

Sets an action observer for this action. Set to null to specify no observer or to disable observaiton.

Parameters:

observer - the observer that will be told of each event when this action is executed.

clearAllActionsObservers

public void clearAllActionsObservers()

Clears all action observers associated with this action

applicableInState

public final boolean applicableInState(State s,
                        java.lang.String params)

Returns true if this action can be applied in this specified state with the specified parameters. Default behavior is that an action can be applied in any state, but the applicableInState(State, String []) method will need to be override if this is not the case.

Parameters:

s - the state in which to check if this action can be applied

params - a comma delineated String specifying the action object parameters

Returns:

true if this action can be applied in this specified state with the specified parameters; false otherwise.

applicableInState

public boolean applicableInState(State s,
                        java.lang.String[] params)

Returns true if this action can be applied in this specified state with the specified parameters. Default behavior is that an action can be applied in any state, but this will need be overridden if that is not the case.

Parameters:

s - the state to perform the action on

params - a String array specifying the action object parameters

Returns:

whether the action can be performed on the given state

performAction

public final State performAction(State s,
                  java.lang.String params)

Performs this action in the specified state using the specified parameters and returns the resulting state. The input state will not be modified. The method will return a copy of the input state if the action is not applicable in state s with parameters params.

Parameters:

s - the state in which the action is to be performed.

params - a comma delineated String specifying the action object parameters

Returns:

the state that resulted from applying this action

performAction

public State performAction(State s,
                  java.lang.String[] params)

Performs this action in the specified state using the specified parameters and returns the resulting state. The input state will not be modified with a deep copied state returned instead (unless this method is overriden, which may result in a semi-deep copy). If the action is not applicable in state s with parameters params, then a copy of the input state is returned. In general Action subclasses should *NOT* override this method and should instead override the abstract performActionHelper(State, String[]) method. Only override this method if you are seeking to perform memory optimization with semi-shallow copies of states and know what you're doing.

Parameters:

s - the state in which the action is to be performed.

params - a String array specifying the action object parameters

Returns:

the state that resulted from applying this action

isPrimitive

public boolean isPrimitive()

Returns whether this action is a primitive action of the domain or not. A primitive action is defined to be an action that always takes one time step.

Returns:

true if the action is primitive; false otherwise.

getTransitions

public final java.util.List<TransitionProbability> getTransitions(State s,
                                                   java.lang.String params)

Returns the transition probabilities for applying this action in the given state with the given set of parameters. Transition probabilities are specified as list of TransitionProbability objects. The list is only required to contain transitions with non-zero probability. By default, this method assumes that transition dynamics are deterministic and it returns a list with a single TransitionProbability with probability 1 whose state is determined by querying the performAction(State, String []) method. If the transition dynamics are stochastic, then the analogous method getTransitions(State, String []) needs to be overridden.

Parameters:

s - the state from which the transition probabilities when applying this action will be returned.

params - a comma delineated String specifying the action object parameters

Returns:

a List of transition probabilities for applying this action in the given state with the given set of parameters

getTransitions

public java.util.List<TransitionProbability> getTransitions(State s,
                                                   java.lang.String[] params)

Returns the transition probabilities for applying this action in the given state with the given set of parameters. Transition probabilities are specified as list of TransitionProbability objects. The list is only required to contain transitions with non-zero probability. Since not all planning algorithms require the full transition dynamics (and since it's impossible to enumerate them in some infinite state space domains), this method is not requried to be implemented. However, it will throw an UnsupportedOperationException if it is not overriden by the Action subclass if it is called by an algorithm that requires it.

Parameters:

s - the state from which the transition probabilities when applying this action will be returned.

params - a String array specifying the action object parameters

Returns:

a List of transition probabilities for applying this action in the given state with the given set of parameters

deterministicTransition

protected java.util.List<TransitionProbability> deterministicTransition(State s,
                                                            java.lang.String[] params)

Returns the transition dynamics by assuming the action to be deterministic and wrapping the result of a performAction(burlap.oomdp.core.State, String[]) method with a 1.0 probable TransitionProbability object and inserting it in the returned list.

Parameters:

s - the state from which the transition probabilities when applying this action will be returned.

params - a String array specifying the action object parameters

Returns:

a List of one element of type TransitionProbability whose state is the outcome of the performAction(burlap.oomdp.core.State, String[]) method.

getAllApplicableGroundedActions

public java.util.List<GroundedAction> getAllApplicableGroundedActions(State s)

Returns all possible groundings of this action that can be applied in the provided State. To check if a grounded action is applicable in the state, the applicableInState(State, String[]) method is checked. The default behavior of this method is to treat the parameters as possible object bindings, finding all bindings that satisfy the object class typing specified and then checking them against the applicableInState(State, String[]) method. However, this class can also be overridden to provide custom grounding behavior or non-object based parameterizations.

Parameters:

s - the State in which all applicable grounded actions of this Action object should be returned.

Returns:

a list of all applicable GroundedActions of this Action object in in the given State

getAllApplicableGroundedActionsFromActionList

public static java.util.List<GroundedAction> getAllApplicableGroundedActionsFromActionList(java.util.List<Action> actions,
                                                                           State s)

Returns all GroundedActions that are applicable in the given State for all Action objects in the provided list. This method operates by calling the getAllApplicableGroundedActions(State) method on each action and adding all the results to a list that is then returned.

Parameters:

actions - The list of all actions for which grounded actions should be returned.

s - the state

Returns:

a List of all the GroundedActions for all Action in the list that are applicable in the given State

performActionHelper

protected abstract State performActionHelper(State s,
                        java.lang.String[] params)

This method determines what happens when an action is applied in the given state with the given parameters. The State object s may be directly modified in this method since the parent method first copies the input state to pass to this helper method. The resulting state (which may be s) should then be returned.

Parameters:

s - the state to perform the action on

params - a String array specifying the action object parameters

Returns:

the resulting State from performing this action

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object