matrx.world_builder

Module Contents

class WorldBuilder(shape, tick_duration=0.5, random_seed=1, simulation_goal=1000, run_matrx_api=True, run_matrx_visualizer=False, visualization_bg_clr='#C2C2C2', visualization_bg_img=None, verbose=False)

Used to create one or more worlds according to a single blueprint.

worlds(self, nr_of_worlds: int = 100)

A Generator of worlds.

Parameters
nr_of_worldsint (default, 100)

The number of worlds that should be generated.

Yields
GridWorld

A GridWorld, where all random properties and prospects are sampled using the given master seed.

Raises
ValueError

When nr_of_worlds is not an integer. zero or negative.

See also

run()

Start a GridWorld instance.

Examples

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

get_world(self)

Create a single world using the blueprint of this builder.

The returned GridWorld can be started with world.run().

Returns
worldGridWorld

A GridWorld instance representing the create world using this builder.

See also

matrx.grid_world.GridWorld.run()

Start a GridWorld instance.

add_logger(self, logger_class, log_strategy=None, save_path=None, file_name=None, file_extension=None, delimiter=None, **kwargs)

Adds a data logger to the world’s blueprint.

Parameters
logger_classLogger

The class of Logger you wish to add.

log_strategyint, str (default, None)

The logging strategy used. Supports either an integer denoting the number of ticks the logger should be called. Or either one of the following:

  • GridWorldLogger.LOG_ON_LAST_TICK: Log only on last tick.

  • GridWorldLogger.LOG_ON_FIRST_TICK: Log only on first tick.

  • GridWorldLogger.LOG_ON_GOAL_REACHED: Log whenever a goal is reached.

save_pathstring (default, None)

A path to a folder where to save the data. When set to None, a folder “logs” is created and used.

file_namestring (default, None)

The file name of the stored data. When set to None, a name of “_<time_stamp>” will be used. With <time_stamp> the time of world creation.

file_extensionstring (default, None)

The extension of the file. When set to None, “.csv” is used.

delimiterstring (default, None)

The delimiter of the columns in the data file. When set to None, the “;” is used.

**kwargs

Any key word arguments the given logger_class requires.

Raises
ValueError

When the given logger_class is not of (super) type GridWorldLogger.

See also

matrx.logger.logger.GridWorldLogger

The interface class to which the passed logger_class should inherit from.

Logging

The module with predefined loggers for you to use.

Examples

Add a logger that logs all agent actions every tick:

>>> from matrx import WorldBuilder
>>> from matrx.logger import LogActions
>>> builder = WorldBuilder(shape=(10, 10))
>>> builder.add_logger(LogActions)

Add a logger that logs when agents are idle or not every time a goal will be achieved:

>>> from matrx import WorldBuilder
>>> from matrx.logger import LogIdleAgents, GridWorldLogger
>>> builder = WorldBuilder(shape=(10, 10))
>>> builder.add_logger(LogIdleAgents, log_strategy=GridWorldLogger.LOG_ON_GOAL_REACHED)
add_agent(self, location: Union[tuple, list], agent_brain: AgentBrain, name, customizable_properties: Union[tuple, list] = None, sense_capability: SenseCapability = None, is_traversable: bool = True, team: str = None, possible_actions: list = None, is_movable: bool = None, visualize_size: float = None, visualize_shape: Union[float, str] = None, visualize_colour: str = None, visualize_depth: int = None, visualize_opacity: float = None, visualize_when_busy: bool = None, **custom_properties)

Adds a single agent to the world’s blueprint.

This methods adds an agent body to every created world at the specified location and linked to an instance of the provided agent brain.

All keyword parameters default to None. Which means that their values are obtained from their similar named constants in matrx.defaults.

Parameters
locationtuple or list

The location (x,y) of the to be added agent.

agent_brainAgentBrain

The AgentBrain instance that will control the agent.

namestring

The name of the agent, should be unique to allow the visualisation to have a single web page per agent. If the name is already used, an exception is thrown.

customizable_propertieslist (optional, None)

A list or tuple of names of properties for this agent that can be altered or customized. Either by the agent itself or by other agents or objects. If a property value gets changed that is not in this list than an exception is thrown.

sense_capabilitySenseCapability (optional, None)

The SenseCapability object belonging this this agent’s AgentBody. Used by the GridWorld to pre-filter objects and agents from this agent’s states when querying for actions. Defaults to a SenseCapability that sees all object types within the entire world.

is_traversablebool (optional, None)

Denotes whether other agents and object can move over this agent. It also throws an exception when this is set to False and another object/agent with this set to False is added to the same location.

teamstring (optional, None)

The team name. Used to group agents together. Defaults to this agent’s name + “_team” to signify it forms its own team.

possible_actionslist (optional, None)

A list or tuple of the names of the Action classes this agent can perform. With this you can limit the actions this agent can perform.

is_movablebool (optional, None)

Whether this agent can be moved by other agents (currently this only happens with the DropObjectAction and PickUpAction).

visualize_sizefloat (optional, None)

The size of this agent in its visualisation. A value of 1.0 denotes the full grid location square, whereas a value of 0.5 denotes half, and 0.0 an infinitesimal small size.

visualize_shapeint or string (optional, None)

The shape of this agent in its visualisation. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_colourstring (optional, None)

The colour of this agent in its visualisation. Should be a string hexadecimal colour value.

visualize_depthint (optional, None)

The visualisation depth of this agent in its visualisation. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

visualize_opacityfloat (optional, None)

The opacity of this agent in its visualization. A value of 1.0 means full opacity and 0.0 no opacity.

visualize_when_busybool (optional, None)

Whether to visualize when an agent is busy with a action. True means show this using a loading icon, false means do not show this in the visualizer.

**custom_propertiesdict (optional, None)

Any additional given keyword arguments will be encapsulated in this dictionary. These will be added to the AgentBody as custom_properties which can be perceived by other agents and objects or which can be used or altered (if allowed to by the customizable_properties list) by the AgentBrain or others.

Raises
ValueError

When the given location is not of form (x, y). When the given agent brain does not inheret from AgentBrain When the given name was already assigned to a previous added agent.

Examples

Add a simple patrolling agent that patrols the world.

>>> from matrx import WorldBuilder
>>> from matrx.agents import PatrollingAgentBrain
>>> builder = WorldBuilder(shape=(10, 10))
>>> waypoints = [(0, 0), (10, 0), (10, 10), (0, 10)]
>>> brain = PatrollingAgentBrain(waypoints)
>>> builder.add_agent((5, 5), brain, name="Patroller")

Add an agent with some custom property foo=”bar” and w.

>>> from matrx import WorldBuilder
>>> from matrx.agents import AgentBrain
>>> builder = WorldBuilder(shape=(10, 10))
>>> brain = AgentBrain()
>>> builder.add_agent((5, 5), brain, name="Agent", foo="bar")
add_team(self, agent_brains: Union[list, tuple], locations: Union[list, tuple], team_name, custom_properties=None, sense_capability=None, customizable_properties=None, is_traversable=None, visualize_size=None, visualize_shape=None, visualize_colour=None, visualize_opacity=None, visualize_when_busy=None)

Adds multiple agents as a single team.

All parameters except for the locations and agent_brain default to None. Which means that their values are obtained from the matrx.defaults.

Parameters
agent_brainslist or tuple

The list or tuple of AgentBrain that will control each agent in the team. Should be of the same size as locations.

locationslist or tuple

The list or tuple of locations in the form of (x, y) at which coordinates each agent starts in the team. Should be of the same size as locations.

team_namestring

The name of the team these agents are part of.

custom_propertiesdict or list (optional, default None)

A dictionary of custom properties and their values for all agents or a list of such dictionaries for every agent.

sense_capabilitySenseCapability or list (optional, default None)

A single SenseCapability used for every agent, or a list of those for every given agent.

customizable_propertieslist (optional, default None)

A list of property names that each agent can edit. When it is a list of listed properties, it denotes a unique set of customizable properties for every agent.

is_traversablebool or list (optional, default None)

A list of booleans or a single boolean denoting either for each agent or all agents their traversability.

visualize_sizefloat or list (optional, default None)

A list of floats or a single float denoting either for each agent or all agents their traversability. A value of 0.0 means no size, and a value of 1.0 fills the entire tile.

visualize_shapeint, string or list (optional, default None)

The shape of the agents in the visualisation. When a list, denotes the shape of every agent. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_colourstring or list (optional, default None)

The colours the agents in the visualisation. When a list, denotes the colour separately of every agent. Should be a string hexadecimal colour value.

visualize_opacityfloat or list (optional, default None)

The opacities of the agents in the visualization. When a list, denotes the opacity separately of every agent A value of 1.0 means full opacity and 0.0 no opacity.

visualize_when_busybool or list (optional, default None)

Whether to visualize when an agent is busy with a action. True means show this using a loading icon, false means do not show this in the visualizer. When a list, specifies this for every agent separately.

Raises
ValueError

When a given location is not of form (x, y). When a given agent brain does not inheret from AgentBrain When a given name was already assigned to a previous added agent.

Examples

Add a team of three agents: >>> from matrx import WorldBuilder >>> from matrx.agents import AgentBrain >>> builder = WorldBuilder(shape=(10, 10)) >>> brains = [AgentBrain() for _ in range(3)] >>> locs = [(0, 0), (1, 1), (2, 2)] >>> builder.add_team(brains, locs, “The A Team”)

add_multiple_agents(self, agents, locations, custom_properties=None, sense_capabilities=None, customizable_properties=None, is_traversable=None, teams=None, visualize_sizes=None, visualize_shapes=None, visualize_colours=None, visualize_opacities=None, visualize_depths=None, visualize_when_busy=None)

Add multiple agents to the world.

Parameters
agentslist or tuple

The list or tuple of agent brains that will control each agent. Should be of the same size as locations.

locationslist or tuple

The list or tuple of all agent locations.

custom_propertiesdict or list (optional, default None)

A dictionary of custom properties and their values for all agents or a list of such dictionaries for every agent.

sense_capabilitySenseCapability or list (optional, default None)

A single SenseCapability used for every agent, or a list of those for every given agent.

customizable_propertieslist (optional, default None)

A list of property names that each agent can edit. When it is a list of listed properties, it denotes a unique set of customizable properties for every agent.

is_traversablebool or list (optional, default None)

A list of booleans or a single boolean denoting either for each agent or all agents their traversability.

teamsstring or list (optional, default None)

The team name of all agents or a list of the team for every separate agent.

visualize_sizesfloat or list (optional, default None)

A list of floats or a single float denoting either for each agent or all agents their traversability. A value of 0.0 means no size, and a value of 1.0 fills the entire tile.

visualize_shapesint, string or list (optional, default None)

The shape of the agents in the visualisation. When a list, denotes the shape of every agent. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_coloursstring or list (optional, default None)

The colours the agents in the visualisation. When a list, denotes the colour separately of every agent. Should be a string hexadecimal colour value.

visualize_opacitiesfloat or list (optional, default None)

The opacities of the agents in the visualization. When a list, denotes the opacity separately of every agent A value of 1.0 means full opacity and 0.0 no opacity.

visualize_depthsint or list (optional, default None)

The visualization depths of the agents. When a list, denotes the depths separately of every agent. Larger values, means that they will be visiualized on top.

visualize_when_busybool or list (optional, default None)

Whether to visualize when an agent is busy with a action. True means show this using a loading icon, false means do not show this in the visualizer. When a list, specifies this for every agent separately.

Raises
ValueError

When a given location is not of form (x, y). When a given agent brain does not inheret from AgentBrain When a given name was already assigned to a previous added agent.

Examples

Add a team of three agents: >>> from matrx import WorldBuilder >>> from matrx.agents import AgentBrain >>> builder = WorldBuilder(shape=(10, 10)) >>> brains = [AgentBrain() for _ in range(3)] >>> locs = [(0, 0), (1, 1), (2, 2)] >>> builder.add_team(brains, locs, “The A Team”)

add_agent_prospect(self, location, agent, probability, name='Agent', customizable_properties=None, sense_capability=None, is_traversable=None, team=None, possible_actions=None, is_movable=None, visualize_size=None, visualize_shape=None, visualize_colour=None, visualize_opacity=None, visualize_depth=None, visualize_when_busy=None, **custom_properties)

Adds an agent to the world’s blueprint given a probability.

This methods adds an agent body to every created world at the specified location and linked to an instance of the provided agent brain. It does so based on the provided probability. Meaning that there is probability chance that the agent will be added on the specified location.

All keyword parameters default to None. Which means that their values are obtained from their similar named constants in matrx.defaults.

Parameters
locationtuple or list

The location (x,y) of the to be added agent.

agent_brainAgentBrain

The AgentBrain instance that will control the agent.

probabilityfloat

A float between 0.0 and 1.0. Denotes the probability with which to add this agent when a world is created.

namestring

The name of the agent, should be unique to allow the visualisation to have a single web page per agent. If the name is already used, an exception is thrown.

customizable_propertieslist (optional, None)

A list or tuple of names of properties for this agent that can be altered or customized. Either by the agent itself or by other agents or objects. If a property value gets changed that is not in this list than an exception is thrown.

sense_capabilitySenseCapability (optional, None)

The SenseCapability object belonging this this agent’s AgentBody. Used by the GridWorld to pre-filter objects and agents from this agent’s states when querying for actions. Defaults to a SenseCapability that sees all object types within the entire world.

is_traversablebool (optional, None)

Denotes whether other agents and object can move over this agent. It also throws an exception when this is set to False and another object/agent with this set to False is added to the same location.

teamstring (optional, None)

The team name. Used to group agents together. Defaults to this agent’s name + “_team” to signify it forms its own team.

possible_actionslist (optional, None)

A list or tuple of the names of the Action classes this agent can perform. With this you can limit the actions this agent can perform.

is_movablebool (optional, None)

Whether this agent can be moved by other agents, for example by picking it up and dropping it.

visualize_sizefloat (optional, None)

The size of this agent in its visualisation. A value of 1.0 denotes the full grid location square, whereas a value of 0.5 denotes half, and 0.0 an infinitesimal small size.

visualize_shapeint or string (optional, None)

The shape of this agent in its visualisation. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_colourstring (optional, None)

The colour of this agent in its visualisation. Should be a string hexadecimal colour value.

visualize_depthint (optional, None)

The visualisation depth of this agent in its visualisation. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

visualize_opacityfloat (optional, None)

The opacity of this agent in its visualization. A value of 1.0 means full opacity and 0.0 no opacity.

visualize_when_busybool (optional, None)

Whether to visualize when an agent is busy with a action. True means show this using a loading icon, false means do not show this in the visualizer.

**custom_propertiesdict (optional, None)

Any additional given keyword arguments will be encapsulated in this dictionary. These will be added to the AgentBody as custom_properties which can be perceived by other agents and objects or which can be used or altered (if allowed to by the customizable_properties list) by the AgentBrain or others.

Raises
ValueError

When the given location is not of form (x, y). When the given agent brain does not inheret from AgentBrain When the given name was already assigned to a previous added agent.

Examples

Add an agent with 50% chance of being added to the world. >>> from matrx import WorldBuilder >>> from matrx.agents import AgentBrain >>> builder = WorldBuilder(shape=(10, 10)) >>> brain = AgentBrain() >>> builder.add_agent_prospect((5, 5), brain, 0.5, name=”Agent”, >>> foo=”bar”)

add_object(self, location, name, callable_class=None, customizable_properties=None, is_traversable=None, is_movable=None, visualize_size=None, visualize_shape=None, visualize_colour=None, visualize_depth=None, visualize_opacity=None, **custom_properties)

Adds an environment object to the blueprint.

This environment object can be any object that is a EnvObject or inherits from it.

All optional parameters default to None, meaning that their values are taken from matrx.defaults.

Parameters
locationlist or tuple

The location of the object of the form (x,y).

namestring

The name of the object.

callable_classclass

A class object of the to be added object. Should be EnvObject or any class that inherits from this.

customizable_propertieslist (optional, None)

A list or tuple of names of properties for this object that can be altered or customized. Either by an agent, itself or other objects. If a property value gets changed that is not in this list than an exception is thrown.

is_traversablebool (optional, default None)

Whether this object allows other (traversable) agents and objects to be at the same location.

is_movablebool (optional, default None)

Whether this object can be moved by an agent. For example, by picking it up and dropping it.

visualize_shapeint or string (optional, None)

The shape of this object in its visualisation. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_colourstring (optional, None)

The colour of this object in its visualisation. Should be a string hexadecimal colour value.

visualize_depthint (optional, None)

The visualisation depth of this object in its visualisation. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

visualize_opacityfloat (optional, None)

The opacity of this object in its visualization. A value of 1.0 means full opacity and 0.0 no opacity.

**custom_propertiesdict (optional, None)

Any additional given keyword arguments will be encapsulated in this dictionary. These will be added to the AgentBody as custom_properties which can be perceived by other agents and objects or which can be used or altered (if allowed to by the customizable_properties list) by the AgentBrain or others.

Raises
AssertionError

When the location is not a list or tuple. When the callable_class is not callable.

Examples

Add a standard EnvObject: >>> from matrx import WorldBuilder >>> from matrx.objects import EnvObject >>> builder = WorldBuilder(shape=(10, 10)) >>> builder.add_object((4, 4), “Object”, EnvObject)

add_object_prospect(self, location, name, probability, callable_class=None, customizable_properties=None, is_traversable=None, is_movable=None, visualize_size=None, visualize_shape=None, visualize_colour=None, visualize_depth=None, visualize_opacity=None, **custom_properties)

Adds an object to the blueprint with a certain probability.

This methods adds an object to every created world at the specified location. It does so based on the provided probability. Meaning that there is probability chance that the agent will be added on the specified location.

All keyword parameters default to None. Which means that their values are obtained from their similar named constants in matrx.defaults.

Parameters
locationlist or tuple

The location of the object of the form (x,y).

namestring

The name of the object.

probabilityfloat

A float between 0.0 and 1.0 that denotes the probability of adding this object to the world when it is created.

callable_classclass

A class object of the to be added object. Should be EnvObject or any class that inherits from this.

customizable_propertieslist (optional, None)

A list or tuple of names of properties for this object that can be altered or customized. Either by an agent, itself or other objects. If a property value gets changed that is not in this list than an exception is thrown.

is_traversablebool (optional, default None)

Whether this obejct allows other (traversable) agents and objects to be at the same location.

is_movablebool (optional, None)

Whether this agent can be moved by other agents, for example by picking it up and dropping it.

visualize_shapeint or string (optional, None)

The shape of this object in its visualisation. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_colourstring (optional, None)

The colour of this object in its visualisation. Should be a string hexadecimal colour value.

visualize_depthint (optional, None)

The visualisation depth of this object in its visualisation. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

visualize_opacityfloat (optional, None)

The opacity of this object in its visualization. A value of 1.0 means full opacity and 0.0 no opacity.

**custom_propertiesdict (optional, None)

Any additional given keyword arguments will be encapsulated in this dictionary. These will be added to the AgentBody as custom_properties which can be perceived by other agents and objects or which can be used or altered (if allowed to by the customizable_properties list) by the AgentBrain or others.

Raises
AssertionError

When the location is not a list or tuple. When the callable_class is not callable.

Examples

Add a standard EnvObject with a 50% probability: >>> from matrx import WorldBuilder >>> from matrx.objects import EnvObject >>> builder = WorldBuilder(shape=(10, 10)) >>> builder.add_object_prospect((4, 4), “Object”, 0.5, EnvObject)

add_multiple_objects(self, locations, names=None, callable_classes=None, custom_properties=None, customizable_properties=None, is_traversable=None, visualize_sizes=None, visualize_shapes=None, visualize_colours=None, visualize_depths=None, visualize_opacities=None, is_movable=None)

Add several objects to the blueprint.

These environment objects can be any object that is an EnvObject or inherits from it.

All optional parameters default to None, meaning that their values are taken from matrx.defaults.

Parameters
locationstuple or list

A tuple or list of the form [(x, y), …] specifying each object’s location.

namesstring or list (optional, default None)

A single name for all objects or a list of names for every object. When None, defaults to the name of the provided callable_classes.

callable_classesEnvObject or list (optional, default None)

A single class specifying a environment object or a list of classes for every object. When None, defaults to EnvObject

custom_propertiesdict or list (optional, None)

A dictionary containing all custom property names and their values of a list of such dictionaries for every object.

customizable_propertieslist (optional, None)

A list of properties that agents and objects are allowed to change or a list of such lists for every object.

is_traversablebool or list (optional, None)

Whether all objects are traversable or a list of such booleans to specify this for every object.

visualize_sizesfloat or list (optional, None)

The size of all objects or a list of such sizes for every object.

visualize_shapesint, string or list (optional, None)

The shape of the objects in the visualisation or list of shapes for every object. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_coloursstring or list (optional, None)

The colour of the objects or a list of such colours. As a hexidecimal string.

visualize_depthsint or list (optional, None)

The visualisation depth of the objects in the visualisation or a list of such depths for every object. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

visualize_opacitiesfloat (optional, None)

The opacity of the objects in the visualisation or a list of opacities for every object. A value of 1.0 means full opacity and 0.0 no opacity.

is_movablebool or list (optional, None)

Whether the objects can be moved by an agent or list denoting this for every object. For example, by picking it up and dropping it.

Raises
AssertionError

When the location is not a list or tuple. When the callable_class is not callable.

Examples

Add three standard environment objects with the same name: >>> from matrx import WorldBuilder >>> from matrx.objects import EnvObject >>> builder = WorldBuilder(shape=(10, 10)) >>> locs = [(1, 1), (2, 2), (3, 3)] >>> builder.add_multiple_objects(locs, “Object”, EnvObject)

add_human_agent(self, location, agent, name='HumanAgent', customizable_properties=None, sense_capability=None, is_traversable=None, team=None, possible_actions=None, is_movable=None, visualize_size=None, visualize_shape=None, visualize_colour=None, visualize_depth=None, visualize_opacity=None, visualize_when_busy=None, key_action_map=None, **custom_properties)

Adds an agent that can be controlled by a human user.

This methods adds an agent body to every created world at the specified location and linked to an instance of a HumanAgentBrain which handles user input as received from a visualisation.

All keyword parameters default to None. Which means that their values are obtained from their similar named constants in matrx.defaults.

Parameters
locationtuple or list

The location (x,y) of the to be added agent.

agentHumanAgentBrain

The human agent brain that is linked to this agent. Should be of type HumanAgentBrain or inherit from it.

namestring (optional, default “HumanAgent”)

The name of the agent, should be unique to allow the visualisation to have a single web page per agent. If the name is already used, an exception is raised.

customizable_propertieslist (optional, None)

A list or tuple of names of properties for this agent that can be altered or customized. Either by the agent itself or by other agents or objects. If a property value gets changed that is not in this list than an exception is thrown.

sense_capabilitySenseCapability (optional, None)

The SenseCapability object belonging this this agent’s AgentBody. Used by the GridWorld to pre-filter objects and agents from this agent’s states when querying for actions. Defaults to a SenseCapability that sees all object types within the entire world.

is_traversablebool (optional, None)

Denotes whether other agents and object can move over this agent. It also throws an exception when this is set to False and another object/agent with this set to False is added to the same location.

teamstring (optional, None)

The team name. Used to group agents together. Defaults to this agent’s name + “_team” to signify it forms its own team.

possible_actionslist (optional, None)

A list or tuple of the names of the Action classes this agent can perform. With this you can limit the actions this agent can perform.

is_movablebool (optional, None)

Whether this agent can be moved by other agents (currently this only happens with the DropObjectAction and PickUpAction).

visualize_sizefloat (optional, None)

The size of this agent in its visualisation. A value of 1.0 denotes the full grid location square, whereas a value of 0.5 denotes half, and 0.0 an infinitesimal small size.

visualize_shapeint or string (optional, None)

The shape of this agent in its visualisation. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_colourstring (optional, None)

The colour of this agent in its visualisation. Should be a string hexadecimal colour value.

visualize_depthint (optional, None)

The visualisation depth of this agent in its visualisation. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

visualize_opacityfloat (optional, None)

The opacity of this agent in its visualization. A value of 1.0 means full opacity and 0.0 no opacity.

visualize_when_busybool (optional, None)

Whether to visualize when an agent is busy with a action. True means show this using a loading icon, false means do not show this in the visualizer.

key_action_mapdict (optional, None)

A dictionary that maps keyboard keys in ASCII to action classes. It can be used to translate keystrokes to the agent performing a certain action.

**custom_propertiesdict (optional, None)

Any additional given keyword arguments will be encapsulated in this dictionary. These will be added to the AgentBody as custom_properties which can be perceived by other agents and objects or which can be used or altered (if allowed to by the customizable_properties list) by the AgentBrain or others.

Raises
ValueError

When an agent with the given name was already added previously. When the agent parameter does not inherits from HumanAgentBrain

Examples

Add a standard human controlled agent: >>> from matrx import WorldBuilder >>> from matrx.agents import HumanAgentBrain >>> builder = WorldBuilder(shape=(10, 10))) >>> brain = HumanAgentBrain() >>> builder.add_human_agent((5, 5), brain, name=”Neo”)

Add a human controlled agent with a custom key map: >>> from matrx import WorldBuilder >>> from matrx.agents import HumanAgentBrain >>> from matrx.actions import * >>> builder = WorldBuilder(shape=(10, 10))) >>> brain = HumanAgentBrain() >>> keymap = {8 : MoveNorth, 6: MoveEast, 2: MoveSouth, 4: MoveWest} >>> builder.add_human_agent((5, 5), brain, name=”Morpheus”, >>> key_action_map=keymap)

add_area(self, top_left_location, width, height, name, customizable_properties=None, visualize_colour=None, visualize_opacity=None, **custom_properties)

Adds an area of tiles/surface.

Adds multiple AreaTile objects inside the specified square, including the edges under a single common name.

All keyword parameters default to None. Which means that their values are obtained from their similar named constants in matrx.defaults.

Parameters
top_left_locationlist or tuple

A location of the form (x, y) that specifies the top-left location of the rectangle.

widthint

The width in number of grid squares.

heightint

The height in number of grid squares.

namestring

The name of the area.

customizable_propertieslist (optional, default None)

The properties that agents and objects can modify in all the created tiles.

visualize_colourstring (optional, default None)

The colour of the tiles as a hexidecimal string.

visualize_opacityfloat (optional, default None)

The opacity of the tiles. A value of 1.0 means full opacity and 0.0 no opacity.

**custom_propertieslist (optional, None)
Any additional given keyword arguments will be encapsulated in
this dictionary. These will be added to all the tiles as
custom_properties which can be perceived by other agents and
objects or which can be used or altered (if allowed to by the
customizable_properties list) by agents or objects.
Raises
AssertionError

When the location is not a list or tuple. When the callable_class is not callable.

ValueError

When the width or height is less then 1.

Examples

Add a green area to the world: >>> from matrx import WorldBuilder >>> builder = WorldBuilder(shape=(10, 10)) >>> builder.add_area((3,3), 3, 3, “Grass”, visualize_colour=”#00a000”)

add_smoke_area(self, top_left_location, width, height, name, visualize_colour=None, smoke_thickness_multiplier=1.0, visualize_depth=None, **custom_properties)

Adds a smoke-like area.

This method adds an area where the opacity of the added SmokeTile follow a white noise pattern, mimicking the idea of a fog or body of water.

Parameters
top_left_locationlist or tuple

A location of the form (x, y) that specifies the top-left location of the rectangle.

widthint

The width in number of grid squares.

heightint

The height in number of grid squares.

namestring

The name of the area.

visualize_colourstring (optional, default None)

The colour of the tiles as a hexadecimal string.

visualize_depthint (optional, default None)

The visualisation depth of the area in the visualisation. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

**custom_propertieslist (optional, None)
Any additional given keyword arguments will be encapsulated in
this dictionary. These will be added to all the tiles as
custom_properties which can be perceived by other agents and
objects or which can be used or altered (if allowed to by the
customizable_properties list) by agents or objects.
Raises
AssertionError

When the location is not a list or tuple. When the callable_class is not callable.

Examples

Add an area resembling a body of water: >>> from matrx import WorldBuilder >>> builder = WorldBuilder(shape=(10, 10)) >>> builder.add_smoke_area((3,3), 3, 3, “Lake”, >>> visualize_colour=”#0050a0”)

add_line(self, start, end, name, callable_class=None, customizable_properties=None, is_traversable=None, is_movable=None, visualize_size=None, visualize_shape=None, visualize_colour=None, visualize_depth=None, visualize_opacity=None, **custom_properties)

Adds a line of objects to the blueprint.

This line can be under any angle, and all locations crossed by that line will have an object.

All keyword parameters default to None. Which means that their values are obtained from their similar named constants in matrx.defaults.

Parameters
startlist or tuple

A location of form (x, y) denoting the start of the line.

end

A location of form (x, y) denoting the end of the line.

namestring

The name of the line of objects.

callable_classEnvObject (optional, None)

The object class denoting the objects that should be added. This is EnvObject by default or must be any other class or inherit from this class.

customizable_propertieslist (optional, None)

A list or tuple of names of properties for these objects that can be altered or customized. Either by an agent, itself or other objects. If a property value gets changed that is not in this list, an exception is thrown.

is_traversablebool (optional, default None)

Whether this object allows other (traversable) agents and objects to be at the same location.

is_movablebool (optional, None)

Whether these objects can be moved by agents, for example by picking it up and dropping it.

visualize_sizefloat or list (optional, None)

The size of all objects or a list of such sizes for every object.

visualize_shapeint or string (optional, None)

The shape of this object in its visualisation. Depending on the value it obtains this shape:

  • 0 = a square

  • 1 = a triangle

  • 2 = a circle

  • Path to image or GIF = that image scaled to match the size.

visualize_colourstring (optional, None)

The colour of this object in its visualisation. Should be a string hexadecimal colour value.

visualize_depthint (optional, None)

The visualisation depth of this object in its visualisation. It denotes the ‘layer’ on which it is visualized. A larger value is more on ‘top’.

visualize_opacityfloat (optional, None)

The opacity of this object in its visualization. A value of 1.0 means full opacity and 0.0 no opacity.

**custom_propertiesdict (optional, None)

Any additional given keyword arguments will be encapsulated in this dictionary. These will be added to the AgentBody as custom_properties which can be perceived by other agents and objects or which can be used or altered (if allowed to by the customizable_properties list) by the AgentBrain or others.

Raises
AssertionError

When the location is not a list or tuple. When the callable_class is not callable.

Examples

Add two colored lines in a cross: >>> from matrx import WorldBuilder >>> builder = WorldBuilder(shape=(10, 10)) >>> builder.add_line((0, 0), (10, 10), “Line 1”) >>> builder.add_line((10, 0), (0, 10), “Line 2”)

add_room(self, top_left_location, width, height, name, door_locations=None, with_area_tiles=False, doors_open=False, door_open_colour=None, door_closed_colour=None, door_visualization_opacity=None, wall_visualize_colour=None, wall_visualize_opacity=None, wall_custom_properties=None, wall_customizable_properties=None, area_custom_properties=None, area_customizable_properties=None, area_visualize_colour=None, area_visualize_opacity=None)

Adds a rectangular room withs walls and doors.

This method allows you to create an area surrounded with walls and optional doors.

All keyword parameters default to None. Which means that their values are obtained from their similar named constants in matrx.defaults.

Parameters
top_left_locationlist or tuple

A location of the form (x, y) that specifies the top-left location of the rectangle.

widthint

The width in number of grid squares.

heightint

The height in number of grid squares.

namestring

The name of the room. Shared with all objects.

door_locationslist, (optional, None)

A list of locations on the wall locations that should be replaced by doors. When set to None, no doors will be added.

with_area_tilesbool (optional, False)

Whether the area within the walls should be filled with AreaTile objects. If set to True, the area parameters are used and passed.

doors_openbool (optional, False)

Whether the doors are initially open or closed.

door_open_colour: str (optional, “#006400”)

Colour, as hexidecimal string, when a room door is closed. Defaults to a shade of green.

door_closed_colour: str (optional, “#640000”)

Colour, as hexidecimal string, when a room door is open. Defaults to a shade of red.

door_visualization_opacity: str (optional, 1.0)

Opacity of the object, as a percentge from 0.0 (fully opaque) to 1.0 (no opacity). Defaults to 1.0.

wall_visualize_colourstring (optional, default None)

The colour of the walls.

wall_visualize_opacitystring (optional, default None)

The opacity of the walls.

wall_custom_propertiesdict (optional, default None)

A dictionary of custom properties and their values passed to every wall object.

wall_customizable_propertieslist (optional, default None)

A list of property names that other objects and agents are allowed to adjust.

area_custom_properties(optional, default None)

A dictionary of custom properties and their values passed to every area object. Only used when area tiles are added.

area_customizable_properties(optional, default None)

A list of property names that other objects and agents are allowed to adjust. Only used when area tiles are added.

area_visualize_colour(optional, default None)

The colour of the areas as a hexadeciamal string. Only used when area tiles are added.

area_visualize_opacity(optional, default None)

The opacity of the added area tiles. Only used when area tiles are added.

Raises
AssertionError

When the location is not a list or tuple. When the callable_class is not callable.

ValueError

When the width or height is less then 2. When a door location is not inside a wall.

Examples

Add world boundaries around the grid and a single room with a door and a green area: >>> from matrx import WorldBuilder >>> builder = WorldBuilder(shape=(10, 10)) >>> builder.add_room((0,0), 10, 10, “World bounds”) >>> builder.add_room((3,3), 3, 3, “Room”, door_locations=(4,3), >>> with_area_tiles=True, area_visualize_colour=”#00a000”)

startup(self, media_folder=None)

Start the API and default visualization.

This method allows you to start the API and the default visualization if set in the builder’s constructor.

Parameters
media_folderstring

The path to a folder where additional figures are stored. Providing this path makes those media files accessible to MATRX. It is required if you pass your figures to object shapes.

Raises
ValueError

When the visualizer is set to run but without the API running.

Examples

Create a builder with a running API and visualizer and start these, referring to a custom media folder. >>> from matrx import WorldBuilder >>> builder = WorldBuilder(shape=(10, 10)) >>> media_folder = “media” >>> builder.startup(media_folder)

stop(self)

Stops the running API and default visualisation gracefully.

add_goal(self, world_goal, overwrite=False)

Appends a WorldGoal to the worlds this builder creates.

Parameters
world_goalWorldGoal or list/tuple of WorldGoal

A single world goal or a list/tuple of world goals.

overwritebool (default is False)

Whether to overwrite the already existing goal in the builder.

Examples

Add a single world goal to a builder, overwriting any previously added goals (e.g. through the builder constructor). >>> builder.add_goal(LimitedTimeGoal(100), overwrite=True)

add_collection_goal(self, name, collection_locs, collection_objects, in_order=False, collection_area_colour='#c87800', collection_area_opacity=1.0, overwrite_goals=False)

Adds a goal to the world to collect objects and drop them in a specific area.

This is a helper method to quickly add a CollectionGoal to the world. A CollectionGoal will check if a set of objects with certain property-value combinations are at specified locations (potentially in a fixed order). To do so, location(s) need to be specified that function as such a “drop off zone”. This method add to those locations a CollectionDropOffTile object, which are searched by the CollectionGoal and checks if there the specified objects are at those tiles.

In addition, this method receives a list of dictionaries that represent the kind of objects that need to be collected. Since objects are described as a set of properties and their values, these dictionaries contain such property-value pairs (with the property names as keys, and their values as values).

Finally, this method adds a CollectionGoal that links these collection tiles and the requested objects. This goal checks at each tick if the requested objects are at the specified location(s). If multiple locations are given, the requested objects can be spread out over all of those locations! For example, if a Red Block and Blue Block need to be collected on locations (0, 0) and (1, 0), the goal will be accomplished if both blocks are at either location but also when the Red Block is at (0, 0) and the Blue Block is at (1, 0) or vice versa.

Parameters
collection_locs(x, y) or list/tuple of (x, y)

A single location where the objects need to be collected, or a list/tuple of such locations. A location is a list/tuple of two integers, the x- and y-coordinates respectively.

collection_objectslist/tuple of dicts, or a RandomProperty with such list/tuple

A list or tuple of dictionaries. Each dictionary represents a the properties and their respective values that identify the to be collected object. It can also be a RandomProperty with as values such a list/tuple. This can be used to generate a different collection_objects per world creation.

namestr

The name of the CollectionGoal and the added CollectionTarget and CollectionDropOffTile objects.

in_orderbool (default is False)

Whether the objects need to be collected and dropped of in the order specified by the collection_objects list. If all objects are present but not dropped in the right order, the goal will not be accomplished if this is set to True.

collection_area_colourstr (default is )

The colour of the area on the specified locations representing the drop zone.

collection_area_opacityfloat (default is 1.0)

The opacity of the area on the specified locations representing the drop zone.

overwrite_goalsbool (default is False)

Whether any previously added goals to the builder should be discarded/overwritten.

See also

matrx.goals.goals.CollectionGoal

The CollectionGoal that performs the logic of check that all object(s) are dropped at the drop off tiles.

matrx.objects.standard_objects.CollectionDropOffTile

The tile that represents the location(s) where the object(s) need to be dropped.

matrx.objects.standard_objects.CollectionTarget

The invisible object representing which object(s) need to be collected and (if needed) in which order.

Notes

It is important remember that objects might not be traversable, which prevents them from stacking. So if a goal is made that request 2 objects to be collected on the same location where both objects are not traversable, the goal will never be able to succeed.

Examples

Add a collection gaol that requires agents to collect 2 objects in order. The first with the color “#ff0000” (red) and the second with the color “#0000ff” (blue). Objects can be dropped at either location (0, 0) or (1, 0). The drop off are is called “Dropzone”. >>> order = [{“visualize_colour”: “#ff0000”}, {“visualize_colour”: “#0000ff”}] >>> builder.add_collection_goal(“Dropzone”, [(0, 0), (1, 0)], order, in_order=True)

Add two collection goals, each with the same collection zone. The first goal needs to collect two objects with the colours “#ff0000” (red) and “##0000ff” (blue). The second goal needs to collect two objects with the custom property “is_candy” set to True. Both goals can be satisfied by dropping a red and blue candy, or by dropping a red and blue object that are not candies, and two candies with different colours than red or blue. >>> colored_objects = [{“visualize_colour”: “#ff0000”}, {“visualize_colour”: “#0000ff”}] >>> builder.add_collection_goal(“Colours”, [(0, 0), (1, 0)], colored_objects) >>> candy_objects = [{“is_candy”: True}, {“is_candy”: True}] >>> builder.add_collection_goal(“Candies”, [(0, 0), (1, 0)], candy_objects)

Add a collection goal to collect a red and blue candy but in a different order every time a world is created. The two orders defined here are: first red, then blue OR first blue then red. >>> different_orders = [[{“visualize_colour”: “#ff0000”}, {“visualize_colour”: “#0000ff”}], >>> [{“visualize_colour”: “#0000ff”}, {“visualize_colour”: “#ff0000”}]] >>> rp_order = RandomProperty(values=different_orders) >>> builder.add_collection_goal(“Colours”, [(0, 0), (1, 0)], rp_order, in_order=True)

class RandomProperty(values, distribution=None, allow_duplicates=True)

Represents a object property with random values.

This property is similar to a regular property of any object or agent. The difference is that this represents a set of possible values from which the builder samples using a uniform or provided distribution when creating a new world.

It allows you to assign a value to a property (custom or not) that is different every time a new world is create (e.g. a block that has a different colour each time).