matrx.goals.goals

Module Contents

class WorldGoal

A class that tracks whether the simulation has reached its global goal.

Deprecated since version 2.1.0: WorldGoal will be removed in the future, it is replaced by WorldGoalV2 because the latter works with the matrx.agents.agent_utils.state.State object.

goal_reached(self, grid_world)

Returns whether the global goal of the simulated grid world is accomplished. This method should be overridden by a new goal function.

Parameters

grid_worldGridWorld

An up to date representation of the grid world that will be analyzed in this function on whether a specific coded global goal is reached.

Returns

goal_reachedbool

True when the goal is reached, False otherwise.

get_progress(self, grid_world)

Returns the progress of reaching the global goal in the simulated grid world. This method can be overridden if you want to track the progress. But is not required.

Parameters

grid_worldGridWorld

An up to date representation of the grid world that will be analyzed in this function on how far we are in obtaining the global world goal.

Returns

progressfloat

Representing with 0.0 no progress made, and 1.0 that the goal is reached.

reset(self)

Resets this goal’s completion boolean and returns a copy of this object.

class LimitedTimeGoal(max_nr_ticks)

Bases: matrx.goals.goals.WorldGoal

A world goal that simply tracks whether a maximum number of ticks has been reached.

goal_reached(self, grid_world)

Returns whether the number of specified ticks has been reached.

Parameters

grid_worldGridWorld

An up to date representation of the grid world that will be analyzed in this function on whether a specific coded global goal is reached.

Returns

goal_reachedbool

True when the goal is reached, False otherwise.

Examples

For an example, see matrx.grid_world.__check_simulation_goal()

Checking all simulation goals from e.g. action, world goal, or somewhere else with access to the Gridworld, the function can be used as below:

>>> goal_status = {}
>>> if grid_world.simulation_goal is not None:
>>>     if isinstance(grid_world.simulation_goal, list):
>>>         for sim_goal in grid_world.simulation_goal:
>>>             is_done = sim_goal.goal_reached(grid_world)
>>>             goal_status[sim_goal] = is_done
>>>     else:
>>>         is_done = grid_world.simulation_goal.goal_reached(grid_world)
>>>         goal_status[grid_world.simulation_goal] = is_done
>>>
>>> is_done = np.array(list(goal_status.values())).all()

get_progress(self, grid_world)

Returns the progress of reaching the LimitedTimeGoal in the simulated grid world.

Parameters

grid_worldGridWorld

An up to date representation of the grid world that will be analyzed in this function on how far we are in obtaining the global world goal.

Returns

progressfloat

Representing with 0.0 no progress made, and 1.0 that the goal is reached.

Examples

Checking all simulation goals from e.g. action, world goal, or somewhere else with access to the Gridworld, the function can be used as below. In this example we know there is only 1 simulation goal.

>>> progress = grid_world.simulation_goal.get_progress(grid_world)
>>> print(f"The simulation is {progress * 100} percent complete!")

reset(self)

Resets this goal’s completion boolean and returns a copy of this object.

class CollectionGoal(name, target_name, in_order=False)

Bases: matrx.goals.goals.WorldGoal

A class that tracks whether the simulation has reached its global goal.

Deprecated since version 2.1.0: WorldGoal will be removed in the future, it is replaced by WorldGoalV2 because the latter works with the matrx.agents.agent_utils.state.State object.

goal_reached(self, grid_world)

Returns whether the global goal of the simulated grid world is accomplished. This method should be overridden by a new goal function.

Parameters

grid_worldGridWorld

An up to date representation of the grid world that will be analyzed in this function on whether a specific coded global goal is reached.

Returns

goal_reachedbool

True when the goal is reached, False otherwise.

get_progress(self, grid_world)

Returns the progress of reaching the global goal in the simulated grid world. This method can be overridden if you want to track the progress. But is not required.

Parameters

grid_worldGridWorld

An up to date representation of the grid world that will be analyzed in this function on how far we are in obtaining the global world goal.

Returns

progressfloat

Representing with 0.0 no progress made, and 1.0 that the goal is reached.

classmethod get_random_order_property(cls, possibilities, length=None, with_duplicates=False)

Creates a RandomProperty representing a list of potential objects to collect in a certain order.

Parameters

possibilities: iterable

An iterable (e.g. list, tuple, etc.) of dictionaries representing property_name, property_value pairs that can be collected.

length: int (optional, default None)

The number of objects that need to be sampled from possibilities to be collected.

with_duplicates: bool (optional, default False)

Whether entries in possibilities can occur more than once in the lists.

Returns

RandomProperty

A random property representing all possible lists of collection objects. Each list differs in the order of the objects. If length < len(possibilities), not all objects may be in each list. If with_duplicates=True, some objects might occur more than once in a list. This random property can be given to a CollectionGoal who will sample one of these lists every time a world is run. This allows a world with a CollectionGoal to denote different collection goals each time but still based on all properties in possibilities.

See also

matrx.world_builder.WorldBuilder.add_collection_goal()

The method that receives this return value.

matrx.world_builder.RandomProperty

The class representing a property with a random value each world creation.

Examples

>>> from matrx import WorldBuilder
>>> from matrx.logger import LogActions
>>> from matrx.objects import SquareBlock
>>> from matrx.goals import CollectionGoal
>>> builder = WorldBuilder(shape=(3, 3))
>>> builder.add_object([0, 0], "Red Block", callable_class=SquareBlock, visualize_colour="#eb4034")
>>> builder.add_object([1, 1], "Blue Block", callable_class=SquareBlock, visualize_colour="#3385e8")

Add a collection goal, where we should collect red and blue blocks but every time we run the world, in a different

order. To do so, we need to pass a RandomProperty to add_collection_goal which it uses to sample such an order each created world. We call this utility method to get us such a RandomProperty.

>>> rp_order = CollectionGoal.get_random_order_property([{'visualize_colour': 'eb4034'}, {'visualize_colour': '3385e8'}])
>>> builder.add_collection_goal("Drop", [(2, 2)], rp_order, in_order=True)

reset(self)

Resets this goal’s completion boolean and returns a copy of this object.

class WorldGoalV2

A class that tracks whether the simulation has reached its global goal.

goal_reached(self, world_state, grid_world)

Returns whether the global goal of the simulated grid world is accomplished. This method should be overridden by a new goal.

Parameters

world_stateState

The entire world state. Used to search and read objects within the world to check for world completion.

grid_worldGridWorld

The actual grid world instance. For access to components not present in the world state, such as the messages send between agents and user input from human agents.

Returns

goal_reachedbool

True when the goal is reached, False otherwise.

get_progress(self, world_state, grid_world)

Returns the progress of reaching the global goal in the simulated grid world. This method can be overridden if you want to track the progress. But is not required.

Parameters

world_stateState

The entire world state. Used to search and read objects within the world to check for world completion.

grid_worldGridWorld

The actual grid world instance. For access to components not present in the world state, such as the messages send between agents and user input from human agents.

Returns

progressfloat

Representing with 0.0 no progress made, and 1.0 that the goal is reached.

reset(self)

Resets this goal’s completion boolean and returns a copy of this object.

class LimitedTimeGoalV2(max_nr_ticks)

Bases: matrx.goals.goals.WorldGoalV2

A world goal that simply tracks whether a maximum number of ticks has been reached.

goal_reached(self, world_state, grid_world)

Returns whether the number of specified ticks has been reached.

Parameters

world_stateState

The entire world state. Used to search and read objects within the world to check for world completion.

grid_worldGridWorld

The actual grid world instance. For access to components not present in the world state, such as the messages send between agents and user input from human agents.

Returns

goal_reachedbool

True when the goal is reached, False otherwise.

Examples

For an example, see matrx.grid_world.__check_simulation_goal()

Checking all simulation goals from e.g. action, world goal, or somewhere else with access to the Gridworld, the function can be used as below:

>>> goal_status = {}
>>> if grid_world.simulation_goal is not None:
>>>     if isinstance(grid_world.simulation_goal, list):
>>>         for sim_goal in grid_world.simulation_goal:
>>>             is_done = sim_goal.goal_reached(grid_world)
>>>             goal_status[sim_goal] = is_done
>>>     else:
>>>         is_done = grid_world.simulation_goal.goal_reached(grid_world)
>>>         goal_status[grid_world.simulation_goal] = is_done
>>>
>>> is_done = np.array(list(goal_status.values())).all()

get_progress(self, world_state, grid_world)

Returns the progress of reaching the LimitedTimeGoal in the simulated grid world.

Parameters

world_stateState

The entire world state. Used to search and read objects within the world to check for world completion.

grid_worldGridWorld

The actual grid world instance. For access to components not present in the world state, such as the messages send between agents and user input from human agents.

Returns

progressfloat

Representing with 0.0 no progress made, and 1.0 that the goal is reached.

Examples

Checking all simulation goals from e.g. action, world goal, or somewhere else with access to the Gridworld, the function can be used as below. In this example we know there is only 1 simulation goal.

>>> progress = grid_world.simulation_goal.get_progress(grid_world)
>>> print(f"The simulation is {progress * 100} percent complete!")

reset(self)

Resets this goal’s completion boolean and returns a copy of this object.

class CollectionGoalV2(name, target_name, in_order=False)

Bases: matrx.goals.goals.WorldGoalV2

A class that tracks whether the simulation has reached its global goal.

goal_reached(self, world_state, grid_world)

Returns whether the global goal of the simulated grid world is accomplished. This method should be overridden by a new goal.

Parameters

world_stateState

The entire world state. Used to search and read objects within the world to check for world completion.

grid_worldGridWorld

The actual grid world instance. For access to components not present in the world state, such as the messages send between agents and user input from human agents.

Returns

goal_reachedbool

True when the goal is reached, False otherwise.

get_progress(self, world_state, grid_world)

Returns the progress of reaching the global goal in the simulated grid world. This method can be overridden if you want to track the progress. But is not required.

Parameters

world_stateState

The entire world state. Used to search and read objects within the world to check for world completion.

grid_worldGridWorld

The actual grid world instance. For access to components not present in the world state, such as the messages send between agents and user input from human agents.

Returns

progressfloat

Representing with 0.0 no progress made, and 1.0 that the goal is reached.

classmethod get_random_order_property(cls, possibilities, length=None, with_duplicates=False)

Creates a RandomProperty representing a list of potential objects to collect in a certain order.

Parameters

possibilities: iterable

An iterable (e.g. list, tuple, etc.) of dictionaries representing property_name, property_value pairs that can be collected.

length: int (optional, default None)

The number of objects that need to be sampled from possibilities to be collected.

with_duplicates: bool (optional, default False)

Whether entries in possibilities can occur more than once in the lists.

Returns

RandomProperty

A random property representing all possible lists of collection objects. Each list differs in the order of the objects. If length < len(possibilities), not all objects may be in each list. If with_duplicates=True, some objects might occur more than once in a list. This random property can be given to a CollectionGoal who will sample one of these lists every time a world is run. This allows a world with a CollectionGoal to denote different collection goals each time but still based on all properties in possibilities.

See also

matrx.world_builder.WorldBuilder.add_collection_goal()

The method that receives this return value.

matrx.world_builder.RandomProperty

The class representing a property with a random value each world creation.

Examples

>>> from matrx import WorldBuilder
>>> from matrx.logger import LogActions
>>> from matrx.objects import SquareBlock
>>> from matrx.goals import CollectionGoal
>>> builder = WorldBuilder(shape=(3, 3))
>>> builder.add_object([0, 0], "Red Block", callable_class=SquareBlock, visualize_colour="#eb4034")
>>> builder.add_object([1, 1], "Blue Block", callable_class=SquareBlock, visualize_colour="#3385e8")

Add a collection goal, where we should collect red and blue blocks but every time we run the world, in a different

order. To do so, we need to pass a RandomProperty to add_collection_goal which it uses to sample such an order each created world. We call this utility method to get us such a RandomProperty.

>>> rp_order = CollectionGoal.get_random_order_property([{'visualize_colour': 'eb4034'}, {'visualize_colour': '3385e8'}])
>>> builder.add_collection_goal("Drop", [(2, 2)], rp_order, in_order=True)

reset(self)

Resets this goal’s completion boolean and returns a copy of this object.