matrx.actions.object_actions

Module Contents

class RemoveObject(duration_in_ticks=0)

Bases: matrx.actions.action.Action

Removes an object from the world.

An action that permanently removes an matrx.objects.env_object.EnvObject from the world, which can be any object except for the agent performing the action.

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)

Removes the specified object.

Removes a specific matrx.objects.env_object.EnvObject from the world. Can be any object except for the agent performing the action.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the object is sought according to the object_id parameter.

agent_idstr

The string representing the unique identifier that represents 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.

object_id: str (Optional. Default: None)

The string representing the unique identifier of the matrx.objects.env_object.EnvObject that should be removed. If not given, the closest object is selected. removed.

remove_rangeint (Optional. Default: 1)

The range in which the matrx.objects.env_object.EnvObject should be in for it to be removed.

Returns
RemoveObjectResult

Depicts the action’s success or failure and reason for that result.

See matrx.actions.object_actions.RemoveObjectResult for the results it can contain.

is_possible(self, grid_world, agent_id, **kwargs)

Checks if an object can be removed.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the object is sought according to the object_id parameter.

agent_id: str

The string representing the unique identified that represents 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.

object_id: str (Optional. Default: None)

The string representing the unique identifier of the matrx.objects.env_object.EnvObject that should be removed. If not given, the closest object is selected.

remove_rangeint (Optional. Default: 1)

The range in which the matrx.objects.env_object.EnvObject should be in for it to be removed.

Returns
RemoveObjectResult

The matrx.actions.action.ActionResult depicting the action’s expected success or failure and reason for that result.

See matrx.actions.object_actions.RemoveObjectResult for the results it can contain.

class RemoveObjectResult(result, succeeded)

Bases: matrx.actions.action.ActionResult

ActionResult for a RemoveObjectAction

The results uniquely for RemoveObjectAction are (as class constants):

  • OBJECT_REMOVED: If the object was successfully removed.

  • REMOVAL_FAILED: If the object could not be removed by the matrx.grid_world.GridWorld.

  • OBJECT_ID_NOT_WITHIN_RANGE: If the object is not within specified range.

  • NO_OBJECTS_IN_RANGE: If no objects are within range.

Parameters
result: str

A string representing the reason for the (expected) success or fail of a matrx.actions.object_actions.RemoveObjectAction.

succeeded: bool

A boolean representing the (expected) success or fail of a matrx.actions.object_actions.RemoveObjectAction.

See also

matrx.actions.object_actions.RemoveObjectAction
OBJECT_REMOVED = The object with id `OBJECT_ID` is removed.

Result when no objects were within the specified range.

NO_OBJECTS_IN_RANGE = No objects were in `REMOVE_RANGE`.

Result when the specified object is not within the specified range.

OBJECT_ID_NOT_WITHIN_RANGE = The object with id `OBJECT_ID` is not within the range of `REMOVE_RANGE`.

Result when the world could not remove the object for some reason.

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.

class GrabObject(duration_in_ticks=0)

Bases: matrx.actions.action.Action

Grab and hold objects.

The action that can pick up / grab and hold an matrx.objects.env_object.EnvObject. Cannot be performed on agents (including the agent performing the action). After grabbing / picking up, the object is automatically added to the agent’s inventory and removed from the matrx.grid_world.GridWorld.

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<}

Notes

The actual carrying mechanism of objects is implemented in the matrx.actions.move_actions.Move actions: whenever an agent moves who holds objects, those objects it is holding are also moved with it.

is_possible(self, grid_world, agent_id, world_state, **kwargs)

Checks if the object can be grabbed.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the object is sought according to the object_id parameter.

agent_id: str

The string representing the unique identifier that represents 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.

object_idstr (Optional. Default: None)

The string representing the unique identifier of the matrx.objects.env_object.EnvObject that should be grabbed. When not given, a random object within range is selected.

grab_rangeint (Optional. Default: np.inf)

The range in which the matrx.objects.env_object.EnvObject should be in to be grabbed.

max_objectsint (Optional. Default: np.inf)

The maximum of objects the agent can carry.

Returns
GrabObjectResult

Depicts the action’s expected success or failure and reason for that result.

See matrx.actions.object_actions.GrabObjectResult for the results it can contain.

mutate(self, grid_world, agent_id, world_state, **kwargs)

Grabs an object.

Alters the properties of the agent doing the grabbing, and the object being grabbed (and carried), such that the agent’s inventory contains the entire object and the object being carried properties contains the agent’s id.

The grabbed object is removed from the world, and will only exist inside of the agent’s inventory.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the object is sought according to the object_id parameter.

agent_idstr

The string representing the unique identifier that represents 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.

object_idstr (Optional. Default: None)

The string representing the unique identifier of the matrx.objects.env_object.EnvObject that should be grabbed. When not given, a random object within range is selected.

grab_rangeint (Optional. Default: np.inf)

The range in which the matrx.objects.env_object.EnvObject should be in to be grabbed.

max_objectsint (Optional. Default: np.inf)

The maximum of objects the agent can carry.

Returns
GrabObjectResult

Depicts the action’s expected success or failure and reason for that result.

See matrx.actions.object_actions.GrabObjectResult for the results it can contain.

Notes

A grabbed object resides inside the inventory of an agent, not directly in the world any longer. Hence, if the agent is removed, so is its inventory and all objects herein.

class GrabObjectResult(result, succeeded)

Bases: matrx.actions.action.ActionResult

ActionResult for a GrabObjectAction

The results uniquely for GrabObjectAction are (as class constants):

  • RESULT_SUCCESS: When the object can be successfully grabbed.

  • RESULT_NO_OBJECT: When object_id is not given.

  • RESULT_CARRIES_OBJECT: When the agent already carries the maximum nr. objects.

  • NOT_IN_RANGE: When object_id not within range.

  • RESULT_AGENT: If the object_id is that of an agent.

  • RESULT_OBJECT_CARRIED: When the object is already carried by another agent.

  • RESULT_OBJECT_UNMOVABLE: When the object is not movable.

  • RESULT_UNKNOWN_OBJECT_TYPE: When the object_id does not exists in the matrx.grid_world.GridWorld.

  • FAILED_TO_REMOVE_OBJECT_FROM_WORLD: When the grabbed object cannot be removed from the matrx.grid_world.GridWorld.

Parameters
resultstr

A string representing the reason for a matrx.actions.object_actions.GrabObjectAction (expected) success or fail.

succeededbool

A boolean representing the (expected) success or fail of a matrx.actions.object_actions.GrabObjectAction.

See also

GrabObjectAction
RESULT_SUCCESS = Grab action success

Result when the grabbed object cannot be removed from the matrx.grid_world.GridWorld.

FAILED_TO_REMOVE_OBJECT_FROM_WORLD = Grab action failed; could not remove object with id {OBJECT_ID} from grid.

Result when the specified object is not within range.

NOT_IN_RANGE = Object not in range

Result when the specified object is an agent.

RESULT_AGENT = This is an agent, cannot be picked up

Result when no object was specified.

RESULT_NO_OBJECT = No Object specified

Result when the agent is at its maximum carrying capacity.

RESULT_CARRIES_OBJECT = Agent already carries the maximum amount of objects

Result when the specified object is already carried by another agent.

RESULT_OBJECT_CARRIED = Object is already carried by {AGENT_ID}

Result when the specified object does not exist in the matrx.grid_world.GridWorld

RESULT_UNKNOWN_OBJECT_TYPE = obj_id is no Agent and no Object, unknown what to do

Result when the specified object is not movable.

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.

class DropObject(duration_in_ticks=0)

Bases: matrx.actions.action.Action

Drops a carried object.

The action that can drop an matrx.objects.env_object.EnvObject that is in an agent’s inventory. After dropping, the object is added to the matrx.grid_world.GridWorld.

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<}

Notes

The actual carrying mechanism of objects is implemented in the matrx.actions.move_actions.Move actions: whenever an agent moves who holds objects, those objects it is holding are also moved with it.

is_possible(self, grid_world, agent_id, world_state, **kwargs)

Checks if the object can be dropped.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the matrx.objects.env_object.EnvObject is dropped.

agent_idstr

The string representing the unique identifier that represents 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.

object_idstr (Optional. Default: None)

The string representing the unique identifier of the matrx.objects.env_object.EnvObject that should be dropped. When not given the last object that was grabbed is dropped.

drop_rangeint (Optional. Default: np.inf)

The range in which the object can be dropped, with the agent’s location at its center.

Returns
DropObjectResult

Depicts the action’s expected success or failure and reason for that result.

See matrx.actions.object_actions.DropObjectResult for the results it can contain.

mutate(self, grid_world, agent_id, world_state, **kwargs)

Drops the carried object.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the matrx.objects.env_object.EnvObject is dropped.

agent_idstr

The string representing the unique identifier that represents 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.

object_idstr (Optional. Default: None)

The string representing the unique identifier of the matrx.objects.env_object.EnvObject that should be dropped. When not given the last object that was grabbed is dropped.

drop_rangeint (Optional. Default: np.inf)

The range in which the object can be dropped, with the agent’s location at its center.

Returns
DropObjectResult

The matrx.actions.action.ActionResult depicting the action’s expected success or failure and reason for that result.

See matrx.actions.object_actions.DropObjectResult for the results it can contain.

Raises
Exception

When the object is said to be dropped inside the agent’s location, but the agent and object are intraversable. No other intraversable objects can be on the same location.

class DropObjectResult(result, succeeded, obj_id=None)

Bases: matrx.actions.action.ActionResult

ActionResult for a DropObjectAction.

The results uniquely for GrabObjectAction are (as class constants):

  • RESULT_SUCCESS: When the object is successfully dropped.

  • RESULT_NO_OBJECT: When there is no object in the agent’s inventory.

  • RESULT_NONE_GIVEN: When the given obj_id is not being carried by the agent.

  • RESULT_OBJECT: When the object was intended to drop on the agent’s location and this was not possible or when no suitable drop location could be found.

  • RESULT_UNKNOWN_OBJECT_TYPE: When the object id does not exist (anymore).

  • RESULT_NO_OBJECT_CARRIED: When no objects are carried by the agent.

Parameters
resultstr

A string representing the reason for the (expected) success or fail of an matrx.actions.object_actions.DropObjectAction.

succeededbool

A boolean representing the (expected) success or fail of a matrx.actions.object_actions.DropObjectAction.

See also

GrabObjectAction
RESULT_SUCCESS = Drop action success

Result when there is not object in the agent’s inventory.

RESULT_NO_OBJECT = The item is not carried

Result when the specified object is not in the agent’s inventory.

RESULT_NONE_GIVEN = 'None' used as input id

Result when the specified object should be dropped on an agent.

RESULT_AGENT = Cannot drop item on an agent

Result when the specified object should be dropped on an intraversable object.

RESULT_OBJECT = Cannot drop item on another intraversable object

Result when the specified object does not exist (anymore).

RESULT_UNKNOWN_OBJECT_TYPE = Cannot drop item on an unknown object

Result when the agent is not carrying anything.

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.