matrx.actions.move_actions

Module Contents

class MoveActionResult(result, succeeded)

Bases: matrx.actions.action.ActionResult

ActionResult for a Move action

The results uniquely for Move action are (as class constants):

  • RESULT_SUCCESS: When the MoveAction is possible.

  • RESULT_NO_MOVE: If the agent is already at the location it wishes to move to.

  • RESULT_OCCUPIED: When the new location is occupied by an intraversable agent.

  • RESULT_NOT_PASSABLE_OBJECT: When the new location is occupied by an intraversable object.

  • RESULT_OUT_OF_BOUNDS: When the new location is outside the GridWorld’s bounds.

Parameters
resultstr

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

succeededbool

A boolean representing the (expected) success or fail of a matrx.actions.move_actions.Move.

See also

Move
RESULT_SUCCESS = Move action success

When the agent is already at the location it tries to move to.

RESULT_NO_MOVE = Move action resulted in a new location with the agent already present.

When the move action would lead the agent outside the world bounds.

RESULT_OUT_OF_BOUNDS = Move action out of bounds

When the move action would lead the agent to a location occupied by another agent.

RESULT_OCCUPIED = Move action towards occupied space

When the move action would lead the agent to a location occupied by an intraversable object.

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 Move(duration_in_ticks=0)

Bases: matrx.actions.action.Action

The class wrapping all Move actions.

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

See also

MoveNorth
MoveNorthEast
MoveEast
MoveSouthEast
MoveSouth
MoveSouthWest
MoveWest
MoveNorthWest
Attributes
dx{-1, 0, 1}

The delta change on the x-coordinate.

dy{-1, 0, 1}

The delta change on the y-coordinate.

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveNorth

Bases: matrx.actions.move_actions.Move

Moves the agent North.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = 0

  • delta-y = -1

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveNorthEast

Bases: matrx.actions.move_actions.Move

Moves the agent North-East.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = 1

  • delta-y = -1

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveEast

Bases: matrx.actions.move_actions.Move

Moves the agent East.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = 1

  • delta-y = 0

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveSouthEast

Bases: matrx.actions.move_actions.Move

Moves the agent South-East.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = 1

  • delta-y = 1

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveSouth

Bases: matrx.actions.move_actions.Move

Moves the agent South.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = 0

  • delta-y = 1

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveSouthWest

Bases: matrx.actions.move_actions.Move

Moves the agent South-West.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = -1

  • delta-y = 1

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveWest

Bases: matrx.actions.move_actions.Move

Moves the agent West.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = -1

  • delta-y = 0

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.

class MoveNorthWest

Bases: matrx.actions.move_actions.Move

Moves the agent North-West.

Inherits from matrx.actions.move_actions.Move and sets the delta-x and delta-y as follows:

  • delta-x = -1

  • delta-y = -1

See also

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

Checks if the move is possible.

Checks for the following:

  • If the agent is already at the location it wishes to move to.

  • When the new location is occupied by an intraversable agent.

  • When the new location is occupied by an intraversable object.

  • When the new location is outside the GridWorld’s bounds.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

agent_idstr

The unique identifier for the agent whose location should be changed.

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.

**kwargsdict

Not used.

Returns
MoveActionResult

Whether the MoveAction is expected to be possible.

See matrx.actions.move_actions.MoveActionResult for the results it can contain.

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

Mutates an agent’s location

Changes an agent’s location property based on the attributes dx and dy.

Parameters
grid_worldGridWorld

The matrx.grid_world.GridWorld instance in which the agent resides whose location should be updated.

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.

agent_idstr

The unique identifier for the agent whose location should be changed.

Returns
MoveActionResult

The result of the actual change of the location of an agent. Always returns a success.