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