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 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)¶ 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 thematrx.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 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<}
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 thematrx.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 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<}
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 thematrx.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 thematrx.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.