2D Grid Environment

The module holds implementations for 2D-grid environments where the agents know their neighbors in each of the four cardinal directions. Currently implemented are:

• GridAgent: The base grid agent implementation, should be used inside GridEnvironment. Agent places itself in the environment’s grid and knows its neighbors in the cardinal directions: N, E, S, W. Subclass the agent for your specific needs.

• GridEnvironment: A single process grid environment.

• GridEnvManager: A manager for a single process grid environment.

• GridMultiEnvironment: Multi-processing environment holding several GridEnvironment slaves with managers.

• GridMultiEnvManager: A manager for a multi-processing environment. Used especially if the environment needs to be able to execute commands from external sources, e.g. when used as a part of creamas.ds.DistributedEnvironment.

class creamas.grid.GridAgent(*args, **kwargs)

An agent living in a 2D-grid with four neighbors in cardinal directions.

The agent assumes that its environment is derived from GridEnvironment, and places itself into the grid when it is initialized.

async act(*args, **kwargs)

See creamas.core.agent.CreativeAgent.act.

async rcv(msg)

Receive and handle message coming from another agent.

This method is called from send().

The base implementation does nothing, override in a subclass.

async send(card, msg)

Send message msg to the neighboring agent in the card cardinal direction.

Parameters

• card (str) – ‘N’, ‘E’, ‘S’, or ‘W’.

• msg – Message to the agent.

Returns

Response from the agent

The method calls the neighboring agent’s rcv() with the message and returns any value returned by that agent.

This method will fail silently if there is no neighbor agent in the given cardinal direction.

property neighbors

Map of neighboring agent addresses in cardinal directions: N, E, S, W.

property xy

Agent’s place (coordinate) in the grid, (x, y)-tuple.

class creamas.grid.GridEnvManager(environment)

Manager for GridEnvironment.

get_xy_address(xy)

Get address of the agent in xy coordinate, or None if no such agent exists.

async set_agent_neighbors()

Set neighboring agents for all the agents in the grid.

If the managed grid contains neighboring grids, uses those to correctly set also neighboring agents for agents on the edge of the grid.

This function assumes that:

• Grid is full, i.e. it has maximum number of agents.

• All the (possible) neighboring grids have been initialized and have the maximum number of agents. That is, if managed grid’s neighbor map still points to None, this grid is assumed to be in the edge of the super-grid containing multiple GridEnvironment instances.

async set_grid_neighbor(card, addr)

Set the neighbor grid for the grid in card cardinal direction. The addr should point to thanager* of the neighboring grid.

set_gs(gs)

Set grid size for the managed environment.

set_origin(origin)

Set originating coordinates for the managed environment.

async spawn_n(agent_cls, n, *args, **kwargs)

Spawn n agents to the managed environment. This is a convenience function so that one does not have to repeatedly make connections to the environment to spawn multiple agents with the same parameters.

See spawn() for details.

class creamas.grid.GridEnvironment(base_url, loop, clock, connect_kwargs)

Environment where agents reside in a 2D-grid.

Each agent is connected to neighbors in cardinal directions: N, E, S, W. Grid environments can be horizontally stacked with GridMultiEnvironment.

add_to_grid(agent)

Add agent to the next available spot in the grid.

Returns

(x,y) of the agent in the grid. This is the agent’s overall coordinate in the grand grid (i.e. the actual coordinate of the agent w.t.r origin).

Raises

ValueError if the grid is full.

get_xy(xy, addr=True)

Get the agent with xy-coordinate in the grid. If addr is True, returns only the agent’s address.

If no such agent in the grid, returns None.

Raises

ValueError if xy-coordinate is outside the environment’s grid.

is_full()

GridEnvironment is full when its grid is fully populated with agents.

Returns

True if the grid is full, False otherwise. Will also return False for uninitialized grids with (0,0) grid size.

is_ready()

Grid environment is ready when its grid is full.

See also

GridEnvironment.is_full(), Environment.is_ready()

async set_agent_neighbors()

Set neighbors for each agent in each cardinal direction.

This method assumes that the neighboring GridEnvironment of this grid environment have already been set.

property grid

The agents in the grid. 2D-list with the same size as gs.

property gs

Size of the grid as a 2-tuple. Changing the size of the grid after spawning any agents in the environment will clear the grid, but does not remove the agents from the environment.

property neighbors

Map of neighboring grid environments in cardinal directions.

Acceptable keys: N, E, S, W.

The values are the addresses of the managers in the neighboring grid environments.

property origin

Upper left corner of the grid, [0,0] by default.

You should define the origin before spawning any agents into the environment.

class creamas.grid.GridMultiEnvManager(environment)

Manager agent for GridMultiEnvironment.

async get_xy_address(xy)

Get address of the agent in the environment with given coordinates.

This is a managing function for get_xy_address().

get_xy_environment(xy)

Get environment (address of the manager of that environment) which has agent with given coordinates.

This is a managing function for get_xy_environment().

async set_agent_neighbors()

Set neighbor agents for all the agents in the slave environments.

This is a managing function for creamas.grid.GridMultiEnvironment.set_agent_neighbors().

set_grid_neighbor(card, addr)

Set the neighbor multi-grid for this multi-grid in card cardinal direction. The addr should point to the manager of the neighboring multi-grid.

async set_gs(mgr_addr, gs)

Set grid size for GridEnvironment which manager is in given address.

Parameters

• mgr_addr (str) – Address of the manager agent

• gs – New grid size of the grid environment, iterable with length 2.

async set_neighbors()

Set neighbors for all the agents in all the slave environments.

This is a managing function for creamas.grid.GridMultiEnvironment.set_neighbors().

async set_origin(mgr_addr, origin)

Set originating coordinates for GridEnvironment which manager is in given address.

Parameters

• mgr_addr (str) – Address of the manager agent

• origin – New origin of the grid environment, iterable with length 2.

async set_slave_neighbors()

Set neighbor environments for all the slave environments.

This is a managing function for creamas.grid.GridMultiEnvironment.set_slave_neighbors().

class creamas.grid.GridMultiEnvironment(*args, **kwargs)

Multi-environment which stacks its slave GridEnvironment instances horizontally.

Call creamas.grid.GridMultiEnvironment.set_slave_params() immediately after initializing GridMultiEnvironment!

Note

The manager agents for the slave environments will not be part of grid in the slave environments.

Parameters

• addr – (HOST, PORT) address for the master environment.

• env_cls – Class for the master environment, used to make connections to the slave environments. Must be a subclass of Environment.

• mgr_cls – Class for the multi-environment’s manager.

• name (str) – Name of the environment. Will be shown in logs.

• logger – Optional. Logger for the master environment.

async get_xy_address(xy)

Get address of the agent residing in xy coordinate, or None if no such agent is in this multi-environment.

get_xy_environment(xy)

Get manager address for the environment which should have the agent with given xy coordinate, or None if no such environment is in this multi-environment.

async populate(agent_cls, *args, **kwargs)

Populate all the slave grid environments with agents. Assumes that no agents have been spawned yet to the slave environment grids. This excludes the slave environment managers as they are not in the grids.)

async set_agent_neighbors()

Set neighbors for all the agents in all the slave environments. Assumes that all the slave environments have their neighbors set.

async set_neighbors()

Set neighbors for all slave environments and agents in them.

This is a convenience function for calling set_slave_neighbors() and set_agent_neighbors().

async set_slave_neighbors()

Set neighbor environments for all the slave environments. Assumes that neighbors are set for this multi-environment.

async set_slave_params()

Set origin and grid size for each slave environment.

This method needs to be called before slave environments are populated and agents’ and slave environments’ neighbors are set.

async spawn_slaves(*args, **kwargs)

Spawn slave environments.

Parameters

• slave_addrs – List of (HOST, PORT) addresses for the slave-environments.

• slave_env_cls – Class for the slave environments.

• slave_kwargs – If not None, must be a list of the same size as addrs. Each item in the list containing parameter values for one slave environment.

• slave_mgr_cls – Class of the slave environment managers.

property gs

Grid size for each slave environment.

property neighbors

Map of neighboring multi-environments for this multi-environment. The map’s values are manager addresses for the neighbors.

property origin

Origin of this multi-environment (the xy coordinate of the first agent in the first slave environment).