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 the matrx.agents.agent_brain.AgentBrain.filter_observations() method is called for that agent, and the matrx.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 the action_kwargs in the matrx.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 the matrx.actions.Action. Override this method when implementing a new matrx.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 the matrx.agents.agent_brain.AgentBrain by the matrx.grid_world.GridWorld instance so that an agent is capable of checking when and why an matrx.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 custom matrx.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 an matrx.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 new matrx.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 this matrx.actions.action.Action. The matrx.actions.action.ActionResult.succeeded attribute is used to check if the matrx.actions.action.Action is indeed possible by the matrx.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 an matrx.actions.action.Action would always succeed without actually performing the mutation. Hence, this method only needs to check for general cases. The matrx.actions.action.Action.mutate() itself also returns an matrx.actions.action.ActionResult which denotes the actual success or failure of the Action.

This method is called by the matrx.grid_world.GridWorld iff:

OR

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() and matrx.actions.Action.mutate() should return an matrx.actions.action.ActionResult. With the former it represents the expected success or failure of the matrx.actions.action.Action, with the latter the actual success or failure.

The matrx.actions.action.ActionResult class contain several reasons why an matrx.actions.action.Action may succeed or fail that are being checked by a matrx.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 that matrx.actions.action.Action specific results. This allows an matrx.agents.agent_brain.AgentBrain to directly match the matrx.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.