`matrx.grid_world`¶

Module Contents¶

class GridWorld(shape, tick_duration, simulation_goal, rnd_seed=1, visualization_bg_clr='#C2C2C2', visualization_bg_img=None, verbose=False, world_id=0)¶

The Gridworld is the representation of the world and the core of MATRX

initialize(self, api_info)¶

Initializes the gridworld instance and any connected visualizations via the API, then pauses the GridWorld.

By default the GridWorld starts paused. To make it possible for the user to see the first tick of the GridWorld, before pressing play and starting the simulation, this function initializes the gridworld to tick 0, after which it updates any visualizations via the API, followed by pausing the GridWorld.

Parameters

api_infodictionary

A dictionary which contians information on the API. At least containing the api_thread key with the API thread, and the run_matrx_api key which contains whether the GridWorld should start paused or not. The matrx_paused key can be used to start MATRX paused (default behaviour) or unpaused when using a visualizer and API. If the API is disabled, MATRX always starts unpaused by default.

Optionally the nr_states_to_store key telling the API how many past states (including the current) should be stored (minimum of 1, the current state). Note; too big of a number increases RAM usage!

Examples

Create a world builder and generate 10 worlds and run them: >>> from matrx.world_builder import WorldBuilder >>> builder = WorldBuilder(shape=(10, 10)) >>> for gridworld in builder.worlds(): >>> gridworld.run()

Every gridworld received from builder.worlds() is a GridWorld instance.

run(self, api_info)¶

Runs the gridworld instance until stopped via the visualization or the goal has been achieved.

The gridworld by default starts paused.

Parameters

api_infodictionary: A dictionary which contians information on the API. At least containing the api_thread key with the API thread, and the run_matrx_api key which contains whether the GridWorld should start paused or not.

Examples

Create a world builder and generate 10 worlds and run them: >>> from matrx.world_builder import WorldBuilder >>> builder = WorldBuilder(shape=(10, 10)) >>> for gridworld in builder.worlds(): >>> gridworld.run()

get_env_object(self, requested_id, obj_type=None)¶

Fetch an object or agent from the GridWorld using its ID, optionally checking for its object type.

Parameters

requested_iddictionary: The ID of the object or agent to fetch.
obj_typeClass (optional, default, None): The object class of which the object-to-fetch should be. Can be used as a filter: if the object with id requested_id is not of this class, it is not returned.

Returns

objObject or Agent: Returns the object or agent with ID requested_id of tpe obj_type (if not None). If no object can be found that adheres to these filters, None is returned.

Examples

In an action, world goal, or somewhere else with access to the Gridworld, the function can be used as below. In this example the custom action removes a specific agent from the world when executed.

>>> from matrx.agents import HumanAgent
>>> class YourCustomAction(Action):
>>>     def __init__(...):
>>>         ...
>>>
>>>     def mutate(self, grid_world, agent_id, **kwargs):
>>>         agent = grid_world.get_env_object("HumanAgent_23", HumanAgent)
>>>         del agent

Alternatively, if you know the object ID and type (object or agent) for certain, it can also be fetched as so:

>>> reg_ag = grid_world.registered_agents[agent_id] # fetch agent by ID
>>> env_obj = grid_world.environment_objects[object_id]  # fetch object by ID

get_objects_in_range(self, agent_loc, object_type, sense_range)¶

Get all objects of a specific obj type (normal objects or agent) within a certain range around an agent’s location.

Parameters

agent_locdictionary: The location from which to search in a radius around for objects. Can be any [x,y] location within the GridWorld shape dimensions.
obj_typeClass (optional, default, None): The object class of which the objects-to-find should be.
sense_rangeint: The radius around the agent within which to look for objects.

Returns

objOrderedDict: Returns an ordereddict with the objects and agents of tpe object_type within sense_range blocks of the location passed via agent_loc. If not objects were found, the ordered dict is empty.

Examples

In an action, world goal, or somewhere else with access to the Gridworld, the function can be used as below. In this example all objects of all types (denoted with the “*”) within 5 tiles of the coordinate [3,3] are returned.

>>> objects_in_range = grid_world.get_objects_in_range([3,3], object_type="*", sense_range=5)

remove_from_grid(self, object_id, remove_from_carrier=True)¶

Remove an object from the grid.

Parameters

object_idint: ID of the object to remove
remove_from_carrierBool (optional, default, True): Whether to also remove from agents that are currently carrying the object.

Returns

objBool: Whether the object was sucessfully removed from the grid or not.

Examples

In an action, world goal, or somewhere else with access to the Gridworld, the function can be used as below. In this example the Agent3 is removed from the Grid. >>> succeeded = grid_world.remove_from_grid(object_id=”Agent3”, remove_from_carrier=False)

In this example the object Block5 is removed from the Grid, and any Agents that were carrying it. >>> succeeded = grid_world.remove_from_grid(object_id=”Block5”, remove_from_carrier=True)

property registered_agents(self)¶: Dict: Dictionary of all registered agents, keys are the IDs, values are the registered objects.

property environment_objects(self)¶: Dict: Dictionary of all non-agent environment objects, keys are the IDs, values are the registered objects.

property is_done(self)¶: Bool: Boolean that indicates whether the GridWorld is done: either stopped by the user or due to the goal having been achieved.

property current_nr_ticks(self)¶: Int: Current tick at which the gridworld is.

property grid(self)¶: Numpy 2D array: Numpy array of shape x by y. Each grid[x,y] location contains a list with all object IDs of the objects at that location

property shape(self)¶: list: [x,y] shape of the grid

property simulation_goal(self)¶: WorldGoal: The world goal of type WorldGoal, or a class that extends WorldGoal

property tick_duration(self)¶: float: the desired duration of one tick. The real tick_duration might be longer due to a large amount of processing that needs to be done each tick by one or multiple agents.

matrx.grid_world¶

Module Contents¶

`matrx.grid_world`¶