Grid & Spot

class Melodie.Grid(spot_cls: ClassVar[Spot], scenario=None)

Bases: object

Grid is a widely-used discrete space for ABM. Grid contains many Spot`s, each `Spot could contain several agents.

Parameters:

  • spot_cls – The class of Spot

  • width – The width of Grid

  • height – The height of Grid

  • wrap – If true, the coordinate overflow will be mapped to another end.

  • caching – If true, the neighbors and bound check results will be cached to avoid re-computing.

init_grid()
setup_params(width: int, height: int, wrap=True, caching=True, multi=True)

Setup the parameters of the grid.

Parameters:

  • width – An integer for the grid width.

  • height – An integer for the grid height.

  • wrap – A boolean (default True). If True, an agent moving out of the grid on one side will re-enter from the opposite side.

  • caching – A boolean (default True). If True, the grid caches the neighbors of each spot to improve performance.

  • multi – A boolean (default True). If True, more than one agent can stand on the same spot. If False, an error will be raised when attempting to place multiple agents on one spot.

Returns:

None

setup()

Be sure to inherit this function.

Returns:

None

add_category(category_name: str)

Add agent category :param category_name: :return:

get_spot(x, y) → Spot

Get a Spot at position (x, y)

Parameters:

  • x

  • y

Returns:

The Spot at position (x, y)

get_agent_ids(category: str, x: int, y: int) → Set[int]

Get all agent of a specific category from the spot at (x, y) :param category: :param x: :param y: :return: A set of int, the agent ids.

coords_wrap(x, y)

Wrap the coordination :param x: :param y: :return:

get_agent_neighborhood(agent, radius=1, moore=True, except_self=True)
get_spot_neighborhood(spot, radius=1, moore=True, except_self=True)
add_agent(agent: GridAgent)

Add an agent to the grid

Parameters:

  • agent – An GridAgent object.

  • category – A string, the name of category. The category should be registered.

Returns:

remove_agent(agent: GridAgent)

Remove agent from the grid

Parameters:

agent

Returns:

move_agent(agent: GridAgent, target_x, target_y)

Move agent to target position. :param agent_id: :param category: :param target_x: :param target_y: :return:

get_agent_pos(agent_id: int, category: str) → Tuple[int, int]

Get the agent position at the grid. :param agent_id: :param category: :return:

height()

Get the height of grid

Returns:

height, an int

width()

Get the width of grid

Returns:

width, an int

get_neighbors(agent: GridAgent, radius=1, moore=True, except_self=True)

Get the neighbors of one spot at (x, y).

Parameters:

  • x

  • y

  • radius

  • moore

  • except_self

Returns:

A list of the tuple: (Agent category, Agent id).

get_spot_agents(spot: Spot)

Get agents on the spot.

get_colormap()

Get the role of each spot.

Returns:

A tuple. The first item is a nested list for spot roles, and the second item is a dict for agent roles.

spots_to_json()

Convert spots in this grid into a list of json-serializable dict

Returns:

JSON serializable list

get_empty_spots()

Get all empty spots from grid.

Returns:

a list of empty spot coordinates.

find_empty_spot()
setup_agent_locations(category, initial_placement: Literal['direct', 'random_single'] = 'direct') → None

Add an agent category.

For example, if there are two classes of agents: Wolf(GridAgent) and Sheep(GridAgent), and there are 100 agents with id 0~99 for each class. It is obvious in such a circumstance that we cannot identify an agent only with agent id.So it is essential to use category_name to distinguish two types of agents.

Parameters:

  • category_id – The id of new category.

  • category – An AgentList object

  • initial_placement – A str object stand for initial placement, which can be direct or random_single direct means that the agent is placed at the position of its x and y; random_single means that the agent is placed at a random position.

Returns:

None

set_spot_property(attr_name: str, array_2d)

Extract property values from a 2d-numpy-array and assign to each spot.

rand_move_agent(agent: GridAgent, category, range_x, range_y)

Randomly move an agent with maximum movement range_x in x axis and range_y in y axis.

Parameters:

  • agent – Must be Melodie.GridAgent, not Agent. That is because GridAgent has predefined properties required in Grid.

  • range_x – The activity range of agent on the x axis.

  • range_y – The activity range of agent on the y axis.

For example, if the agent is at (0, 0), range_x=1 and range_y=0, the result can be (-1, 0), (0, 0) or (1, 0). The probability of these three outcomes are equal.

Returns:

(int, int), the new position

get_agent_container(category_id) → AgentList
property agent_categories
class Melodie.Spot(spot_id: int, grid: Grid, x: int = 0, y: int = 0)

Bases: GridItem

get_spot_agents()

Get all agents on the spot.

Returns:

a list of grid agent.

get_style()