matrx.actions.action
¶
Main module for the core’s Action class.
Module Contents¶
-
class
Action
(duration_in_ticks=0)¶ Contains the effects of an action on the world.
This class is empty and should be overridden if you want to make a new action that is not yet supported. You may also extend other actions, but all MATRX’ actions inherit from this class.
- Parameters
- duration_in_ticksint
Optional, default:
1
. Should be zero or larger.The default duration of this action in ticks during which the
matrx.grid_world.GridWorld
blocks the agent performing other actions. By default this is 1, meaning that all actions of this type will take both the tick in which it was decided upon and the subsequent tick. When the agent is blocked / busy with an action, only thematrx.agents.agent_brain.AgentBrain.filter_observations()
method is called for that agent, and thematrx.agents.agent_brain.AgentBrain.decide_on_action()
method is skipped. This means that agents that are busy with an action can only perceive the world but not decide on a new action untill the action has completed.An agent can overwrite the duration of an action by returning the
action_duration
in theaction_kwargs
in thematrx.agents.agent_brain.AgentBrain.decide_on_action()
method, as so:return >action_name<, {'action_duration': >ticks<}
-
mutate
(self, grid_world, agent_id, world_state, **kwargs)¶ Method that mutates the world.
This method is allowed to mutate a
matrx.grid_world.GridWorld
instance according to the purposes of thematrx.actions.Action
. Override this method when implementing a newmatrx.actions.action.Action
.- Parameters
- grid_worldGridWorld
The GridWorld instance that should be mutated according to the Action’s intended purpose.
- agent_idstring
The unique identifier of the agent performing this action.
- world_stateState
The State object representing the entire world. Can be used to simplify search of objects and properties when performing an action. Note that this is the State of the entire world, not that of the agent performing the action.
- **kwargs
The set of keyword arguments provided by the agent that decided upon this action. When overriding this method and setting required arguments, the
matrx.grid_world.GridWorld
will take responsibility in checking whether the agent provided these. Hence, it is not required to do so here.
- Returns
- ActionResult
An instance of the
matrx.actions.Action.ActionResult
class, or an inherited class thereof, which denotes whether the mutation actually succeeded or not, together with the reason why. This result is passed to thematrx.agents.agent_brain.AgentBrain
by thematrx.grid_world.GridWorld
instance so that an agent is capable of checking when and why anmatrx.actions.action.Action
succeeded or failed.
See also
matrx.grid_world.GridWorld
Contains additional functions to make the implementation of
matrx.actions.action.Action
simpler.ActionResult
Contains a description on how to create an instance of
matrx.actions.action.ActionResult
, or how to override it for your own custommatrx.actions.action.Action
.
Notes
This method is called by the
matrx.grid_world.GridWorld
iff:An
matrx.agents.agent_brain.AgentBrain
of an agent decided upon this action.It is the turn of the agent to take an action.
The implemented
matrx.actions.Action.is_possible()
method returned anmatrx.actions.Action.ActionResult.succeeded
denoting success.The action_duration has passed.
Furthermore, it is important to remember that the given :class:matrx.grid_world.GridWorld` instance, represents the actual world. Any change to this instance are immediately reflected in the world.
-
is_possible
(self, grid_world, agent_id, world_state, **kwargs)¶ Checks if the Action is possible.
This method analyses a
matrx.grid_world.GridWorld
instance to check if the Action is possible to perform. Override this method when implementing a newmatrx.actions.action.Action
.- Parameters
- grid_worldGridWorld
The GridWorld instance that should be used to check if this Action is possible.
- agent_idstring
The unique identifier of the agent performing this action.
- world_stateState
The State object representing the entire world. Can be used to simplify search of objects and properties when checking if an action can be performed. Note that this is the State of the entire world, not that of the agent performing the action.
- kwargsdictionary
The set of keyword arguments provided by the Agent that decided upon this action. When overriding this method and setting required arguments, the GridWorld will take responsibility in checking whether the Agent provided these. Hence, it is not required to do so here.
- Returns
- ActionResult
The expected
matrx.actions.action.ActionResult
when performing thismatrx.actions.action.Action
. Thematrx.actions.action.ActionResult.succeeded
attribute is used to check if thematrx.actions.action.Action
is indeed possible by thematrx.grid_world.GridWorld
.
Warning
This method should not change anything in this instance. This is reserved for the
matrx.actions.action.Action.mutate()
method as any change here will be reflected in the world.See also
GridWorld
Contains additional functions to make the implementation of Actions simpler.
ActionResult
Contains a description on how to create an ActionResult.
Notes
It is important to understand that this function does not have to guarantee the success of an
matrx.actions.action.Action
. It might be impossible to check if anmatrx.actions.action.Action
would always succeed without actually performing the mutation. Hence, this method only needs to check for general cases. Thematrx.actions.action.Action.mutate()
itself also returns anmatrx.actions.action.ActionResult
which denotes the actual success or failure of the Action.This method is called by the
matrx.grid_world.GridWorld
iff:An
matrx.agents.agent_brain.AgentBrain
of an agent decided upon this action.It is the turn of the agent to take an action.
The action_duration has passed.
OR
An
matrx.agents.agent_brain.AgentBrain
requested if a certainmatrx.actions.action.Action
is possible. (Requested functionality: See Issue #46)
-
class
ActionResult
(result, succeeded)¶ Represents the generic (expected) result of an action.
This class functions as a simple wrapper around a boolean representing the success (True) or failure (False) of the (expected) mutation of an
matrx.actions.action.Action
, as well as the reason for it.The
matrx.actions.action.ActionResult
class contains several generic reasons for a succeed or fail as constant class attributes.- Parameters
- resultstr
A string representing the reason for the (expected) success or fail of an
matrx.actions.action.Action
.- succeededbool
A boolean representing the (expected) success or fail of an
matrx.actions.action.Action
.
See also
Action
The super-class whose children return an ActionResult
Notes
Both the methods
matrx.actions.Action.is_possible()
andmatrx.actions.Action.mutate()
should return anmatrx.actions.action.ActionResult
. With the former it represents the expected success or failure of thematrx.actions.action.Action
, with the latter the actual success or failure.The
matrx.actions.action.ActionResult
class contain several reasons why anmatrx.actions.action.Action
may succeed or fail that are being checked by amatrx.grid_world.GridWorld
instance. These are:IDLE_ACTION: Always given when an AgentBrain decided upon returning None (the idle action)
AGENT_WAS_REMOVED: Always given when an agent does not exist anymore in the GridWorld.
AGENT_NOT_CAPABLE: Always given when the Action an AgentBrain decided upon is not an Action that agent should be capable of.
UNKNOWN_ACTION: Always given when the Action name an AgentBrain decided upon is not recognized as a class name of an Action or some class inheriting from Action. Could be caused by either that class not existing or because it is never imported anywhere (and hence is not on the path the GridWorld searches in).
When creating a new
matrx.actions.action.Action
class, you can also extend this class with your own. This allows you to set your own constants representing reasons for thatmatrx.actions.action.Action
specific results. This allows anmatrx.agents.agent_brain.AgentBrain
to directly match thematrx.actions.ActionResult.result
with a constant and potentially adjust its behavior.-
IDLE_ACTION
= The action is None, hence the agent will idle which always succeeds.¶ Result string for when the agent was removed before performing its action.
-
AGENT_WAS_REMOVED
= Agent {AGENT_ID} was removed during this tick, cannot perform anymore actions.¶ Result when the action succeeded or is expected to succeed.
-
ACTION_SUCCEEDED
= The action succeeded.¶ Result when the action is not expected to succeed.
-
ACTION_NOT_POSSIBLE
= The `is_possible(...)` method returned False. Signalling that the action was not possible.¶ Result when the agent is not capable of performing that action.
-
AGENT_NOT_CAPABLE
= The action could not be performed, as the agent is not capable of performing this action.¶ Result when the action name does not represent an
Action
class
-
UNKNOWN_ACTION
= The action is not known to the environment.¶ Deprecated: Use IDLE_ACTION instead.