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 insideGridEnvironment
. Agent places itself in the environment’sgrid
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 severalGridEnvironment
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 ofDistributedEnvironment
.
-
class
creamas.grid.
GridAgent
(*args, **kwargs)[source]¶ 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
rcv
(msg)[source]¶ 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)[source]¶ 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.
-
async
-
class
creamas.grid.
GridEnvManager
(environment)[source]¶ Manager for
GridEnvironment
.-
get_xy_address
(xy)[source]¶ Get address of the agent in xy coordinate, or None if no such agent exists.
-
async
set_agent_neighbors
()[source]¶ 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 multipleGridEnvironment
instances.
-
-
class
creamas.grid.
GridEnvironment
(base_url, loop, clock, connect_kwargs)[source]¶ 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)[source]¶ 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)[source]¶ 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
()[source]¶ 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
()[source]¶ Grid environment is ready when its grid is full.
See also
GridEnvironment.is_full()
,Environment.is_ready()
-
async
set_agent_neighbors
()[source]¶ 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)[source]¶ Manager agent for
GridMultiEnvironment
.-
async
get_xy_address
(xy)[source]¶ Get address of the agent in the environment with given coordinates.
This is a managing function for
get_xy_address()
.
-
get_xy_environment
(xy)[source]¶ 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
()[source]¶ Set neighbor agents for all the agents in the slave environments.
This is a managing function for
set_agent_neighbors()
.
-
set_grid_neighbor
(card, addr)[source]¶ 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)[source]¶ 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
()[source]¶ Set neighbors for all the agents in all the slave environments.
This is a managing function for
set_neighbors()
.
-
async
set_origin
(mgr_addr, origin)[source]¶ 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
()[source]¶ Set neighbor environments for all the slave environments.
This is a managing function for
set_slave_neighbors()
.
-
async
-
class
creamas.grid.
GridMultiEnvironment
(*args, **kwargs)[source]¶ Multi-environment which stacks its slave
GridEnvironment
instances horizontally.Call
set_slave_params()
immediately after initializingGridMultiEnvironment
!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)[source]¶ Get address of the agent residing in xy coordinate, or
None
if no such agent is in this multi-environment.
-
get_xy_environment
(xy)[source]¶ 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)[source]¶ 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
()[source]¶ Set neighbors for all the agents in all the slave environments. Assumes that all the slave environments have their neighbors set.
-
async
set_neighbors
()[source]¶ Set neighbors for all slave environments and agents in them.
This is a convenience function for calling
set_slave_neighbors()
andset_agent_neighbors()
.
-
async
set_slave_neighbors
()[source]¶ Set neighbor environments for all the slave environments. Assumes that
neighbors
are set for this multi-environment.
-
async
set_slave_params
()[source]¶ 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)[source]¶ 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).