matrx.actions.door_actions

Module Contents

class OpenDoorAction(duration_in_ticks=0)

Bases: matrx.actions.action.Action

Action that opens doors.

The action that opens a specific door within a given range from the agent.

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)

Opens a door in the world.

Mutates the door_status of an matrx.objects.simple_objects.Door in the matrx.grid_world.GridWorld to be open (and as such passable). It does so only if the object_id exists, is a matrx.objects.simple_objects.Door, and is within door_range.

Parameters

grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the door 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 door that should be opened. If none is given, the closest door is selected.

door_rangeint

Optional. Default: np.inf

The maximum allowed distance between the agent and the door for the agent to be able to open that door.

Returns

OpenDoorActionResult

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

See matrx.actions.simple_objects.OpenDoorActionResult for the results it can return.

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

Check if the OpenDoorAction is possible.

Parameters

grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the door

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 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 door that should be opened. If none is given, the closest door is selected.

door_rangeint

Optional. Default: np.inf

The maximum allowed distance between the agent and the door for the agent to be able to open that door.

Returns

OpenDoorActionResult

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

See matrx.actions.simple_objects.OpenDoorActionResult for the results it can return.

class CloseDoorAction(duration_in_ticks=0)

Bases: matrx.actions.action.Action

Action that closes doors.

The action that closes a specific door within a given range from the agent.

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)

Closes a door in the world.

Mutates the door_status of an matrx.objects.simple_objects.Door in the matrx.grid_world.GridWorld to be closed (and as such not passable). It does so only if the object_id exists, is a matrx.objects.simple_objects.Door, and is within door_range.

Parameters

grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the door 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 door that should be opened. If none is given, the closest door is selected.

door_rangeint

Optional. Default: np.inf

The maximum allowed distance between the agent and the door for the agent to be able to close that door.

Returns

OpenDoorActionResult

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

See matrx.actions.simple_objects.CloseDoorActionResult for the results it can return.

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

Check if the CloseDoorAction is possible.

Parameters

grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the door

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 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 door that should be opened. If none is given, the closest door is selected.

door_rangeint

Optional. Default: np.inf

The maximum allowed distance between the agent and the door for that agent to be able to close that door.

Returns

OpenDoorActionResult

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

See matrx.actions.door_actions.CloseDoorActionResult for the results it can return.

class CloseDoorActionResult(result, succeeded)

Bases: matrx.actions.action.ActionResult

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.

class OpenDoorActionResult(result, succeeded)

Bases: matrx.actions.action.ActionResult

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.