public abstract class Action
extends java.lang.Object
Action
definition includes a name for the action,
the preconditions for the action to be executable, and, potentially, the transition dynamics if the Action
implementation
implements the FullActionModel
interface.
Action
is closely associated with an implementation of the GroundedAction
class. A GroundedAction
differs from an Action
in
that it includes any parameter assignments necessary to execute the action that is provided to the appropriate
Action
definition method.
Domain
with which this Action
is to be associated are
specified in a constructor;
for example, Action(String, burlap.oomdp.core.Domain)
.
performActionHelper(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
,applicableInState(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
,isPrimitive()
,isParameterized()
getAssociatedGroundedAction()
and getAllApplicableGroundedActions(burlap.oomdp.core.states.State)
. GroundedAction
is provided
as a method argument. The provided GroundedAction
is how an Action
implementation is told with which parameters it is being applied. If your action is is not parameterized, then this method argument
can be ignored.
performActionHelper(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
method should have the affect of sampling a transition from applying this Action
in the input State
with the specified parameters and returning the sampled outcome. This method is always called indirectly by the performAction(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
method, which first makes a copy of the input state to be passed to performActionHelper(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
.
Therefore, you can directly modify the input state of performActionHelper(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
and return it if that is easiest.
This method will be used by planning
algorithms that use sampled transitions instead of enumerating the full transition dynamics or by deterministic planning
algorithms where there is not expected to ever be more than on possible outcome of an action. In general this method should always
be implemented. However, in some rare cases, it may not even be possible to define a model that can sample transitions
from arbitrary input states.
In such cases, it is okay to have this method throw a runtime exception instead of implementing it, but that means you
will only ever be able to use this action indirectly by applying it in an Environment
,
which should know how to execute it (for example, by telling a robot to execute the action in the real world).
applicableInState(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
method is how preconditions can be specified.
If you do not override this method, then the default behavior is that the action will have no preconditions and can be applied
in any state. This method takes as input a State
and the parameters for this action (if any),
and returns true if the action can be applied in that state and false otherwise.
isPrimitive()
method should usually return true and should only return false for special hierarchical actions like an Option
.
SimpleAction
,
which is useful for defining non-parameterized primitive actions without preconditions, because it implements every abstract method except performActionHelper(burlap.oomdp.core.states.State, GroundedAction)
.
Otherwise these methods will need to be implemented to define the parameterization of your action.
isParameterized()
method should be overriden and set to return true. Next, as noted previously, an GroundedAction
implementation
stores a set of parameter assignments that need to be provided to apply your parameterized Action
.
Therefore, for custom parameterizations, you will need to subclass GroundedAction
to include data
members for parameter assignments and the getAssociatedGroundedAction()
should return an instance of your custom
GroundedAction
with its GroundedAction.action
datamember
pointing to this Action
. The parameter assignments in the returned GroundedAction
do not need to be specified; this method serves as a means for simply generating an instance of the associated GroundedAction
.
getAllApplicableGroundedActions(burlap.oomdp.core.states.State)
method should return a list of GroundedAction
instances that cover the space of all possible parameterizations of the action for in the input State
. However,
the returned list should only include GroundedAction
instances that satisfy the
applicableInState(burlap.oomdp.core.states.State, GroundedAction)
method. Do *NOT* include GroundedAction
objects
that are not applicable in the input list.
GroundedAction
that is returned by these methods, you can have any kind of Action
parametrization that you'd like. That said, A common form of Action
parameterization is an action that operates on OO-MDP
ObjectInstance
references in a state (for example, stacking on block on another
in BlocksWorld
. Therefore, if you would like to have a OO-MDP object parameterization,
rather than define your own subclass, you should consider subclassing the ObjectParameterizedAction
class. See it's documentation for more details.
performInEnvironment(burlap.oomdp.singleagent.environment.Environment, burlap.oomdp.singleagent.GroundedAction)
method.
This method handles having an action executed in some Environment
rather than simulated.
In general, this method does not
need to be overridden for the vast majority of cases (one exception is hierarchical actions like the Option
class, which
overrides it to have a sequence of primitive actions applied in the environment).
Typically, LearningAgent
's will execute actions in the Environment
from which they're learning using this method.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
|
Constructor and Description |
---|
Action() |
Action(java.lang.String name,
Domain domain) |
Modifier and Type | Method and Description |
---|---|
void |
addActionObserver(ActionObserver observer)
Sets an action observer for this action.
|
abstract boolean |
applicableInState(State s,
GroundedAction groundedAction)
Returns true if this action can be applied in this specified state with the parameters
specified by the provided
GroundedAction
Default behavior is that an action can be applied in any state,
but this will need be overridden if that is not the case. |
void |
clearAllActionsObservers()
Clears all action observers associated with this action
|
protected java.util.List<TransitionProbability> |
deterministicTransition(State s,
GroundedAction groundedAction)
Returns the transition dynamics by assuming the action to be deterministic and wrapping the result of a
performAction(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction) method with a 1.0 probable TransitionProbability
object and inserting it in the returned list. |
boolean |
equals(java.lang.Object obj) |
abstract 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
GroundedAction s that are applicable in the given State for all Action objects in the provided list. |
abstract GroundedAction |
getAssociatedGroundedAction()
Returns a
GroundedAction instance that points to this Action ,
but does not have any parameters--if any--set. |
Domain |
getDomain()
Returns the domain to which this action belongs.
|
GroundedAction |
getGroundedAction(java.lang.String... strParams)
Returns the
GroundedAction instance associated with this action with its parameters set to the provided
string representation of the parameters. |
java.lang.String |
getName()
Returns the name of the action
|
int |
hashCode() |
abstract boolean |
isParameterized()
Returns true if this action is parameterized; false otherwise.
|
abstract boolean |
isPrimitive()
Returns whether this action is a primitive action of the domain or not.
|
State |
performAction(State s,
GroundedAction groundedAction)
Performs this action in the specified state using the specified parameters and returns the resulting state.
|
protected abstract State |
performActionHelper(State s,
GroundedAction groundedAction)
This method determines what happens when an action is applied in the given state with the given parameters.
|
EnvironmentOutcome |
performInEnvironment(Environment env,
GroundedAction groundedAction)
Executes this action with the specified parameters in the provided environment and returns the
EnvironmentOutcome result. |
protected java.lang.String name
protected Domain domain
protected java.util.List<ActionObserver> actionObservers
public Action()
public Action(java.lang.String name, Domain domain)
public final java.lang.String getName()
public final Domain getDomain()
public void addActionObserver(ActionObserver observer)
observer
- the observer that will be told of each event when this action is executed.public void clearAllActionsObservers()
public abstract boolean applicableInState(State s, GroundedAction groundedAction)
GroundedAction
Default behavior is that an action can be applied in any state,
but this will need be overridden if that is not the case.s
- the state to perform the action ongroundedAction
- the GroundedAction
specifying the parameters to usepublic EnvironmentOutcome performInEnvironment(Environment env, GroundedAction groundedAction)
EnvironmentOutcome
result.env
- the environment in which the action should be performed.groundedAction
- the GroundedAction
specifying the parameters to useEnvironmentOutcome
specifying the result of the action execution in the environmentpublic State performAction(State s, GroundedAction groundedAction)
performActionHelper(State, burlap.oomdp.singleagent.GroundedAction)
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.s
- the state in which the action is to be performed.groundedAction
- the GroundedAction
specifying the parameters to usepublic abstract boolean isPrimitive()
public abstract boolean isParameterized()
Action
is parameterized; false if it is not.protected java.util.List<TransitionProbability> deterministicTransition(State s, GroundedAction groundedAction)
performAction(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
method with a 1.0 probable TransitionProbability
object and inserting it in the returned list.s
- the state from which the transition probabilities when applying this action will be returned.groundedAction
- the GroundedAction
specifying the parameters to useTransitionProbability
whose state is the outcome of the performAction(burlap.oomdp.core.states.State, burlap.oomdp.singleagent.GroundedAction)
method.public abstract GroundedAction getAssociatedGroundedAction()
GroundedAction
instance that points to this Action
,
but does not have any parameters--if any--set.GroundedAction
instance.public GroundedAction getGroundedAction(java.lang.String... strParams)
GroundedAction
instance associated with this action with its parameters set to the provided
string representation of the parameters. This method works by first calling an the getAssociatedGroundedAction()
method of this object, and then calling the AbstractGroundedAction.initParamsWithStringRep(String[])
method
to set its parameters with the string representations. Consequently, the provided GroundedAction
implementation must implement the AbstractGroundedAction.initParamsWithStringRep(String[])
for this method to work.strParams
- the parameters of the action specified with their string representation.GroundedAction
instance.public abstract java.util.List<GroundedAction> getAllApplicableGroundedActions(State s)
State
. To check if a grounded
action is applicable in the state, the applicableInState(State, burlap.oomdp.singleagent.GroundedAction)
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, burlap.oomdp.singleagent.GroundedAction)
method. However, this class can also be overridden to provide custom
grounding behavior or non-object based parametrization.s
- the State
in which all applicable grounded actions of this Action
object should be returned.GroundedAction
s of this Action
object in in the given State
public static java.util.List<GroundedAction> getAllApplicableGroundedActionsFromActionList(java.util.List<Action> actions, State s)
GroundedAction
s 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.actions
- The list of all actions for which grounded actions should be returned.s
- the stateList
of all the GroundedAction
s for all Action
in the list that are applicable in the given State
protected abstract State performActionHelper(State s, GroundedAction groundedAction)
performAction(burlap.oomdp.core.states.State, GroundedAction)
first copies the input state to pass
to this helper method. The resulting state (which may be s) should then be returned.s
- the state to perform the action ongroundedAction
- the GroundedAction
specifying the parameters to usepublic boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object